pi-usereq 0.11.0 → 0.12.0

package/src/core/req-reset-command.ts

@@ -0,0 +1,323 @@
+/**
+ * @file
+ * @brief Implements the specialized `req-reset` slash-command workflow.
+ * @details Performs non-agentic prompt-orchestration recovery by preserving the current execution-session transcript when available, restoring the original session-backed `base-path`, force-removing every generated sibling worktree and matching branch, and returning deterministic cleanup facts to the extension command handler. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem removal.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  normalizeGitWorktreePrefix,
+  type UseReqConfig,
+} from "./config.js";
+import { ReqError } from "./errors.js";
+import {
+  deletePromptWorktree,
+  getPromptCommandErrorContext,
+  preservePromptCommandExecutionTranscript,
+  restorePromptCommandExecution,
+  type PromptCommandExecutionPlan,
+} from "./prompt-command-runtime.js";
+import { resolveRuntimeGitPath } from "./runtime-project-paths.js";
+
+/**
+ * @brief Declares the fixed slash-command description for `req-reset`.
+ * @details Preserves a deterministic human-facing label for the dedicated non-agentic recovery command while keeping the implementation independent from bundled prompt Markdown files. Access complexity is O(1).
+ */
+export const REQ_RESET_COMMAND_DESCRIPTION = "Reset req workflow state, restore base-path, and remove generated worktrees";
+
+/**
+ * @brief Describes the prepared execution facts for one `req-reset` run.
+ * @details Stores the validated project base, resolved git root, sibling-worktree parent directory, generated-name matcher, and optional persisted prompt execution plan used for transcript preservation plus base-path restoration. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface ReqResetCommandPlan {
+  basePath: string;
+  gitPath: string;
+  parentPath: string;
+  worktreeNamePattern: RegExp;
+  promptRequest: PromptCommandExecutionPlan | undefined;
+}
+
+/**
+ * @brief Describes the outcome of one `req-reset` execution attempt.
+ * @details Captures the last valid session-bound context, transcript-preservation and base-path-restoration facts, removed generated worktree and branch names, and one aggregated failure string when any recovery step fails. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface ReqResetCommandExecutionResult {
+  activeContext: ReqResetCommandContext | undefined;
+  transcriptPreserved: boolean;
+  restoredBasePath: boolean;
+  removedWorktreeDirs: string[];
+  removedBranchNames: string[];
+  errorMessage?: string;
+}
+
+/**
+ * @brief Describes the session-bound context surface reused during `req-reset` recovery.
+ * @details Reuses the session-switching contract already accepted by `restorePromptCommandExecution(...)` so the dedicated reset command can restore the original session without depending on concrete pi runtime classes. The alias is compile-time only and introduces no runtime cost.
+ */
+type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1];
+
+/**
+ * @brief Executes one synchronous subprocess and captures UTF-8 output.
+ * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
+ * @param[in] command {string[]} Executable plus argument vector.
+ * @param[in] cwd {string} Working directory for the subprocess.
+ * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ */
+function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+  return spawnSync(command[0]!, command.slice(1), {
+    cwd,
+    encoding: "utf8",
+  });
+}
+
+/**
+ * @brief Escapes one literal string for safe JavaScript regular-expression reuse.
+ * @details Prefixes every regular-expression metacharacter with `\\` so generated worktree-name patterns can embed persisted prefixes and repository basenames without introducing unintended matcher semantics. Runtime is O(n) in string length. No external state is mutated.
+ * @param[in] text {string} Literal text fragment.
+ * @return {string} Regular-expression-safe literal fragment.
+ */
+function escapeReqResetRegExpLiteral(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+/**
+ * @brief Builds the generated-worktree name matcher used by `req-reset` cleanup.
+ * @details Reuses the configured worktree prefix plus repository basename, accepts any sanitized branch token between those fixed segments and the final execution identifier, and constrains the timestamp suffix to the documented `YYYYMMDDHHMMSS` shape. Runtime is O(p) in combined prefix and project-name length. No external state is mutated.
+ * @param[in] gitRoot {string} Absolute runtime git root.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {RegExp} Matcher for generated prompt-command worktree and branch names.
+ * @satisfies REQ-309, REQ-310, REQ-311
+ */
+function buildReqResetWorktreeNamePattern(gitRoot: string, config: UseReqConfig): RegExp {
+  const worktreePrefix = normalizeGitWorktreePrefix(config.GIT_WORKTREE_PREFIX);
+  const projectName = path.basename(gitRoot);
+  return new RegExp(
+    `^${escapeReqResetRegExpLiteral(worktreePrefix)}${escapeReqResetRegExpLiteral(projectName)}-.+-\\d{14}$`,
+    "u",
+  );
+}
+
+/**
+ * @brief Lists every registered git worktree root for one repository.
+ * @details Executes `git worktree list --porcelain`, extracts each `worktree <path>` record, resolves every listed path to an absolute form, and returns the ordered list used by generated-worktree cleanup. Runtime is dominated by one git subprocess plus O(n) parsing in listed worktree count. Side effects include subprocess creation.
+ * @param[in] gitRoot {string} Absolute runtime git root.
+ * @return {string[]} Absolute registered worktree-root paths.
+ * @throws {ReqError} Throws when git worktree enumeration fails.
+ */
+function listReqResetRegisteredWorktreeRoots(gitRoot: string): string[] {
+  const listResult = runCapture(["git", "worktree", "list", "--porcelain"], gitRoot);
+  if (listResult.error || listResult.status !== 0) {
+    throw new ReqError("ERROR: Unable to enumerate git worktrees for req-reset.", 1);
+  }
+  return listResult.stdout
+    .split(/\r?\n/u)
+    .filter((line) => line.startsWith("worktree "))
+    .map((line) => path.resolve(line.slice("worktree ".length)));
+}
+
+/**
+ * @brief Lists sibling directories whose names match the generated-worktree contract.
+ * @details Reads the repository parent directory, keeps only direct child directories whose basenames match the supplied generated-name pattern, and resolves each candidate to an absolute path so `req-reset` can remove unregistered leftover directories as well as registered git worktrees. Runtime is dominated by directory enumeration plus O(n) matcher cost. Side effects are limited to filesystem reads.
+ * @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+ * @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+ * @return {string[]} Absolute sibling directory paths whose basenames match the generated-name contract.
+ * @throws {ReqError} Throws when directory enumeration fails.
+ */
+function listReqResetSiblingWorktreeRoots(
+  parentPath: string,
+  worktreeNamePattern: RegExp,
+): string[] {
+  const normalizedParentPath = path.resolve(parentPath);
+  let siblingEntries: fs.Dirent[];
+  try {
+    siblingEntries = fs.readdirSync(normalizedParentPath, { withFileTypes: true });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new ReqError(
+      `ERROR: Unable to inspect sibling worktrees in ${normalizedParentPath}: ${errorMessage}.`,
+      1,
+    );
+  }
+  return siblingEntries
+    .filter((entry) => entry.isDirectory() && worktreeNamePattern.test(entry.name))
+    .map((entry) => path.join(normalizedParentPath, entry.name));
+}
+
+/**
+ * @brief Lists every generated sibling worktree candidate targeted by `req-reset`.
+ * @details Unions registered git-worktree roots with matching sibling directories so cleanup covers both registered worktrees and unregistered leftover directories, then sorts the canonical absolute paths for deterministic deletion order. Runtime is dominated by git worktree enumeration plus sibling-directory scanning. Side effects are limited to subprocess creation and filesystem reads.
+ * @param[in] parentPath {string} Absolute directory containing sibling worktree roots.
+ * @param[in] gitRoot {string} Absolute runtime git root.
+ * @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+ * @return {string[]} Sorted absolute worktree-root paths targeted for deletion.
+ * @throws {ReqError} Throws when git worktree or sibling-directory enumeration fails.
+ */
+function listReqResetMatchingWorktreeRoots(
+  parentPath: string,
+  gitRoot: string,
+  worktreeNamePattern: RegExp,
+): string[] {
+  const matchingRoots = new Set<string>();
+  for (const worktreeRootPath of listReqResetRegisteredWorktreeRoots(gitRoot)) {
+    if (worktreeNamePattern.test(path.basename(worktreeRootPath))) {
+      matchingRoots.add(path.resolve(worktreeRootPath));
+    }
+  }
+  for (const siblingRootPath of listReqResetSiblingWorktreeRoots(parentPath, worktreeNamePattern)) {
+    matchingRoots.add(path.resolve(siblingRootPath));
+  }
+  return [...matchingRoots].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * @brief Lists every matching generated branch targeted by `req-reset`.
+ * @details Executes `git branch --list --format=%(refname:short)`, filters the local branch inventory through the generated-name matcher, and returns a sorted list so later forced branch deletion remains deterministic. Runtime is dominated by one git subprocess plus O(n) parsing in listed branch count. Side effects include subprocess creation.
+ * @param[in] gitRoot {string} Absolute runtime git root.
+ * @param[in] worktreeNamePattern {RegExp} Generated-worktree name matcher.
+ * @return {string[]} Sorted local branch names targeted for deletion.
+ * @throws {ReqError} Throws when local branch enumeration fails.
+ */
+function listReqResetMatchingBranchNames(
+  gitRoot: string,
+  worktreeNamePattern: RegExp,
+): string[] {
+  const branchResult = runCapture(["git", "branch", "--list", "--format=%(refname:short)"], gitRoot);
+  if (branchResult.error || branchResult.status !== 0) {
+    throw new ReqError("ERROR: Unable to enumerate git branches for req-reset.", 1);
+  }
+  return branchResult.stdout
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line !== "" && worktreeNamePattern.test(line))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * @brief Prepares the specialized `req-reset` execution plan.
+ * @details Resolves the active project base into a runtime git root, derives the sibling-worktree parent directory and generated-name matcher from the same prefix plus repository-basename contract used by prompt-command worktree generation, and keeps only worktree-backed persisted prompt execution plans for transcript-preserving base-path restoration. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] projectBase {string} Absolute project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] promptRequest {PromptCommandExecutionPlan | undefined} Pending or active prompt execution plan when available.
+ * @return {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+ * @throws {ReqError} Throws when the repository root cannot be resolved.
+ * @satisfies REQ-306, REQ-309, REQ-310, REQ-311
+ */
+export function prepareReqResetCommandExecution(
+  projectBase: string,
+  config: UseReqConfig,
+  promptRequest?: PromptCommandExecutionPlan,
+): ReqResetCommandPlan {
+  const basePath = path.resolve(projectBase);
+  const gitPath = resolveRuntimeGitPath(basePath);
+  if (!gitPath) {
+    throw new ReqError("ERROR: Unable to resolve git repository for req-reset.", 1);
+  }
+  const normalizedGitPath = path.resolve(gitPath);
+  const resetPromptRequest = promptRequest?.worktreeDir
+    && promptRequest.worktreeRootPath
+    && promptRequest.worktreePath
+    ? promptRequest
+    : undefined;
+  return {
+    basePath,
+    gitPath: normalizedGitPath,
+    parentPath: path.resolve(normalizedGitPath, ".."),
+    worktreeNamePattern: buildReqResetWorktreeNamePattern(normalizedGitPath, config),
+    promptRequest: resetPromptRequest,
+  };
+}
+
+/**
+ * @brief Executes the specialized `req-reset` recovery and cleanup workflow.
+ * @details Preserves the execution-session transcript into the original session file when a worktree-backed prompt execution plan is still available, restores the original session-backed `base-path` through the shared prompt-command restoration helper, force-removes every matching sibling worktree directory, force-removes every remaining matching local branch, and aggregates any failure diagnostics without rolling back successful cleanup steps. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file reads and writes, active-session replacement, host-process cwd mutation, worktree deletion, branch deletion, and filesystem reads.
+ * @param[in] plan {ReqResetCommandPlan} Prepared recovery and cleanup plan.
+ * @param[in] ctx {ReqResetCommandContext | undefined} Optional session-bound command context.
+ * @return {Promise<ReqResetCommandExecutionResult>} Recovery and cleanup outcome facts.
+ * @satisfies REQ-305, REQ-307, REQ-308, REQ-309, REQ-310, REQ-313
+ */
+export async function executeReqResetCommandExecution(
+  plan: ReqResetCommandPlan,
+  ctx?: ReqResetCommandContext,
+): Promise<ReqResetCommandExecutionResult> {
+  let activeContext = ctx;
+  let transcriptPreserved = plan.promptRequest === undefined;
+  let restoredBasePath = plan.promptRequest === undefined;
+  const removedWorktreeDirs: string[] = [];
+  const removedBranchNames: string[] = [];
+  const errorMessages: string[] = [];
+
+  if (plan.promptRequest !== undefined) {
+    try {
+      preservePromptCommandExecutionTranscript(plan.promptRequest);
+      transcriptPreserved = true;
+    } catch (error) {
+      transcriptPreserved = false;
+      errorMessages.push(error instanceof Error ? error.message : String(error));
+    }
+    try {
+      activeContext = await restorePromptCommandExecution(plan.promptRequest, activeContext);
+      restoredBasePath = true;
+    } catch (error) {
+      return {
+        activeContext: (getPromptCommandErrorContext(error) ?? activeContext) as ReqResetCommandContext | undefined,
+        transcriptPreserved,
+        restoredBasePath: false,
+        removedWorktreeDirs,
+        removedBranchNames,
+        errorMessage: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  let matchingWorktreeRoots: string[] = [];
+  try {
+    matchingWorktreeRoots = listReqResetMatchingWorktreeRoots(
+      plan.parentPath,
+      plan.gitPath,
+      plan.worktreeNamePattern,
+    );
+  } catch (error) {
+    errorMessages.push(error instanceof Error ? error.message : String(error));
+  }
+
+  for (const worktreeRootPath of matchingWorktreeRoots) {
+    const worktreeDir = path.basename(worktreeRootPath);
+    try {
+      deletePromptWorktree(plan.basePath, worktreeDir, worktreeRootPath);
+      removedWorktreeDirs.push(worktreeDir);
+    } catch (error) {
+      errorMessages.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  try {
+    const matchingBranchNames = listReqResetMatchingBranchNames(plan.gitPath, plan.worktreeNamePattern);
+    for (const branchName of matchingBranchNames) {
+      const deleteResult = runCapture(["git", "branch", "-D", branchName], plan.gitPath);
+      if (deleteResult.error || deleteResult.status !== 0) {
+        const diagnostic = deleteResult.stderr.trim()
+          || deleteResult.stdout.trim()
+          || deleteResult.error?.message
+          || `Unable to remove branch ${branchName}.`;
+        errorMessages.push(`ERROR: git branch -D failed for ${branchName}: ${diagnostic}`);
+        continue;
+      }
+      removedBranchNames.push(branchName);
+    }
+  } catch (error) {
+    errorMessages.push(error instanceof Error ? error.message : String(error));
+  }
+
+  return {
+    activeContext,
+    transcriptPreserved,
+    restoredBasePath,
+    removedWorktreeDirs,
+    removedBranchNames,
+    errorMessage: errorMessages.length > 0
+      ? errorMessages.join(" ")
+      : undefined,
+  };
+}

package/src/core/resources.ts

@@ -65,33 +65,16 @@ export function readBundledPrompt(promptName: string): string {
 }
 
 /**
- * @brief Extracts the YAML-front-matter `description` field from one bundled prompt.
- * @details Parses only the leading front-matter block, resolves the first scalar `description` entry, strips one matching pair of wrapping quotes, and unescapes quoted apostrophe or quote characters used in prompt metadata. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
+ * @brief Extracts the first Markdown level-one heading from one bundled prompt.
+ * @details Removes one optional leading YAML front-matter block, scans the remaining markdown body for the first line that begins with `# `, and returns the heading payload without the marker or surrounding whitespace. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
  * @param[in] promptName {string} Prompt identifier without the `.md` suffix.
- * @return {string} Normalized prompt description or the empty string when the front matter does not declare one.
+ * @return {string} First `# ` heading payload, or the empty string when no level-one heading exists.
  */
 export function readBundledPromptDescription(promptName: string): string {
   const promptText = readBundledPrompt(promptName);
-  const frontMatterMatch = promptText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
-  if (!frontMatterMatch) {
-    return "";
-  }
-  const descriptionLine = frontMatterMatch[1]
-    .split(/\r?\n/)
-    .find((line) => line.startsWith("description:"));
-  if (!descriptionLine) {
-    return "";
-  }
-  const rawValue = descriptionLine.slice("description:".length).trim();
-  const unquotedValue = rawValue.length >= 2
-    && ((rawValue.startsWith('"') && rawValue.endsWith('"'))
-      || (rawValue.startsWith("'") && rawValue.endsWith("'")))
-    ? rawValue.slice(1, -1)
-    : rawValue;
-  return unquotedValue
-    .replace(/\\"/g, '"')
-    .replace(/\\'/g, "'")
-    .trim();
+  const promptBody = promptText.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/, "");
+  const headingMatch = promptBody.match(/^# (.+?)\s*$/m);
+  return headingMatch?.[1]?.trim() ?? "";
 }
 
 /**

package/src/core/settings-menu.ts

@@ -9,7 +9,7 @@ import { Container, SettingsList, Text, type Component, type SettingItem, type S
 
 /**
  * @brief Describes one selectable pi-usereq settings-menu choice.
- * @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, right-column current value, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, right-column current value, optional inline-cycle values, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
  */
 export interface PiUsereqSettingsMenuChoice {
   id: string;
@@ -18,6 +18,7 @@ export interface PiUsereqSettingsMenuChoice {
   value: string;
   valueTone?: "default" | "dim";
   disabled?: boolean;
+  values?: readonly string[];
   description: string;
 }
 
@@ -35,12 +36,12 @@ export interface PiUsereqSettingsMenuBridge {
 
 /**
  * @brief Describes optional behavior overrides for one settings-menu render.
- * @details Carries the caller-selected initial focus row so menu re-renders can
- * preserve selection after an in-place toggle or value edit. The interface is
- * compile-time only and introduces no runtime cost.
+ * @details Carries the caller-selected initial focus row, the optional dynamic choice supplier used to rebuild dependent rows after inline toggles, and the optional inline-change callback used to persist `SettingsList` value cycles without closing the menu. The interface is compile-time only and introduces no runtime cost.
  */
 export interface PiUsereqSettingsMenuOptions {
   initialSelectedId?: string;
+  getChoices?: () => PiUsereqSettingsMenuChoice[];
+  onChange?: (choiceId: string, newValue: string) => void;
 }
 
 /**
@@ -162,7 +163,7 @@ function createImmediateSelectionComponent(choiceId: string, done: (value?: stri
 
 /**
  * @brief Builds `SettingsList` items from one menu-choice vector.
- * @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier only for enabled rows. Runtime is O(n) in choice count. No external state is mutated.
+ * @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, inline-cycle values, and descriptions into `SettingItem` records. Non-disabled rows with `values` cycle inline on `Enter` or `Space`, while other non-disabled rows resolve the outer custom UI through the immediate submenu bridge. Runtime is O(n) in choice count. No external state is mutated.
  * @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
  * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
  * @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
@@ -182,19 +183,49 @@ function buildSettingItems(
     currentValue: choice.valueTone === "dim"
       ? theme.fg("dim", choice.value)
       : choice.value,
-    submenu: choice.disabled
+    values: choice.disabled || choice.values === undefined
+      ? undefined
+      : [...choice.values],
+    submenu: choice.disabled || choice.values !== undefined
       ? undefined
       : () => createImmediateSelectionComponent(choice.id, done),
   }));
 }
 
+/**
+ * @brief Writes one best-effort selected row index into a `SettingsList` instance.
+ * @details Uses reflective access so pi-usereq can preserve focus across menu re-renders without depending on the private field at compile time. Runtime is O(1). Side effect: mutates the underlying `SettingsList` selection state when the field exists.
+ * @param[in,out] settingsList {SettingsList} Mutable settings-list instance.
+ * @param[in] selectedIndex {number} Zero-based row index to restore.
+ * @return {void} No return value.
+ */
+function setSettingsListSelectedIndex(
+  settingsList: SettingsList,
+  selectedIndex: number,
+): void {
+  Reflect.set(settingsList as object, "selectedIndex", selectedIndex);
+}
+
+/**
+ * @brief Reads the current selected row index from a `SettingsList` instance.
+ * @details Uses reflective access so pi-usereq can report the current focused row through the offline bridge without referencing the private field in the static type system. Runtime is O(1). No external state is mutated.
+ * @param[in] settingsList {SettingsList} Settings-list instance.
+ * @return {number | undefined} Zero-based selected row index when available.
+ */
+function getSettingsListSelectedIndex(
+  settingsList: SettingsList,
+): number | undefined {
+  const selectedIndex = Reflect.get(settingsList as object, "selectedIndex");
+  return typeof selectedIndex === "number" ? selectedIndex : undefined;
+}
+
 /**
  * @brief Renders one shared pi-usereq settings menu and resolves the selected action.
- * @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, and optional disabled rows. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+ * @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, optional disabled rows, and inline toggle cycles that do not close the menu. When callers provide `getChoices(...)`, dependent rows are rebuilt after inline changes while preserving focus on the changed row. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering and caller-owned inline-change callbacks.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] title {string} Menu title displayed in the heading and offline bridge.
  * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
- * @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override.
+ * @param[in] options {PiUsereqSettingsMenuOptions | undefined} Optional initial-focus override plus inline-change behavior.
  * @return {Promise<string | undefined>} Selected choice identifier or `undefined` when cancelled.
  * @satisfies REQ-151, REQ-152, REQ-153, REQ-154, REQ-156, REQ-192
  */
@@ -211,22 +242,43 @@ export async function showPiUsereqSettingsMenu(
       0,
       0,
     );
-    const settingsList = new SettingsList(
-      buildSettingItems(theme, choices, done),
-      Math.min(Math.max(choices.length, 1), 12),
-      buildPiUsereqSettingsListTheme(theme),
-      () => undefined,
-      () => done(undefined),
-    );
-    const initialSelectedIndex = options.initialSelectedId === undefined
-      ? 0
-      : choices.findIndex((choice) => choice.id === options.initialSelectedId);
-    if (initialSelectedIndex >= 0) {
-      (settingsList as SettingsList & { selectedIndex: number }).selectedIndex = initialSelectedIndex;
-    }
-    container.addChild(titleText);
-    container.addChild(new Text("", 0, 0));
-    container.addChild(settingsList);
+    const spacer = new Text("", 0, 0);
+    let currentChoices = options.getChoices?.() ?? choices;
+    let settingsList: SettingsList;
+
+    const buildSettingsList = (
+      menuChoices: PiUsereqSettingsMenuChoice[],
+      selectedChoiceId?: string,
+    ): SettingsList => {
+      const nextSettingsList = new SettingsList(
+        buildSettingItems(theme, menuChoices, done),
+        Math.min(Math.max(menuChoices.length, 1), 12),
+        buildPiUsereqSettingsListTheme(theme),
+        (choiceId, newValue) => {
+          options.onChange?.(choiceId, newValue);
+          rebuildMenu(choiceId);
+        },
+        () => done(undefined),
+      );
+      const initialSelectedIndex = selectedChoiceId === undefined
+        ? 0
+        : menuChoices.findIndex((choice) => choice.id === selectedChoiceId);
+      if (initialSelectedIndex >= 0) {
+        setSettingsListSelectedIndex(nextSettingsList, initialSelectedIndex);
+      }
+      return nextSettingsList;
+    };
+
+    const rebuildMenu = (selectedChoiceId?: string): void => {
+      currentChoices = options.getChoices?.() ?? choices;
+      settingsList = buildSettingsList(currentChoices, selectedChoiceId);
+      container.clear();
+      container.addChild(titleText);
+      container.addChild(spacer);
+      container.addChild(settingsList);
+    };
+
+    rebuildMenu(options.initialSelectedId);
 
     const component: PiUsereqSettingsMenuComponent = {
       render(width: number): string[] {
@@ -242,13 +294,18 @@ export async function showPiUsereqSettingsMenu(
       },
       __piUsereqSettingsMenu: {
         title,
-        choices,
-        selectedChoiceId: initialSelectedIndex >= 0 ? choices[initialSelectedIndex]?.id : undefined,
+        get choices(): PiUsereqSettingsMenuChoice[] {
+          return currentChoices;
+        },
+        get selectedChoiceId(): string | undefined {
+          const selectedIndex = getSettingsListSelectedIndex(settingsList) ?? 0;
+          return currentChoices[selectedIndex]?.id;
+        },
         selectByLabel(label: string): boolean {
-          const choice = choices.find(
+          const choice = currentChoices.find(
             (candidate) => candidate.label === label || candidate.id === label,
           );
-          if (!choice || choice.disabled) {
+          if (!choice) {
             return false;
           }
           done(choice.id);

package/src/core/tool-runner.ts

@@ -239,15 +239,15 @@ export function runFilesTokens(files: string[]): ToolResult {
 }
 
 /**
- * @brief Generates the monolithic references markdown for explicit files.
- * @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
+ * @brief Generates the monolithic summary markdown for explicit files.
+ * @details Delegates to `generateMarkdown(...)`, keeps output paths relative to the caller cwd, and returns the Python-compatible summary markdown document through stdout. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] files {string[]} Explicit file paths.
  * @param[in] cwd {string} Base directory used for relative output paths. Defaults to `process.cwd()`.
  * @param[in] verbose {boolean} When `true`, emit per-file progress diagnostics to stderr.
  * @return {ToolResult} Successful tool result containing monolithic markdown.
  * @satisfies REQ-011, REQ-076, REQ-077, REQ-078, REQ-079
  */
-export function runFilesReferences(files: string[], cwd = process.cwd(), verbose = false): ToolResult {
+export function runFilesSummarize(files: string[], cwd = process.cwd(), verbose = false): ToolResult {
   try {
     return ok(`${generateMarkdown(files, verbose, cwd)}\n`);
   } catch (error) {
@@ -286,8 +286,8 @@ export function runFilesSearch(argsList: string[], enableLineNumbers = false, ve
 }
 
 /**
- * @brief Generates the monolithic references markdown for configured source directories.
- * @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible references document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
+ * @brief Generates the monolithic summary markdown for configured source directories.
+ * @details Resolves the project base, collects configured source files, prepends the repository file-structure markdown block, and returns the Python-compatible summary document through stdout. Runtime is O(F log F + S). Side effects are limited to filesystem reads and optional stderr logging.
  * @param[in] projectBase {string} Candidate project root.
  * @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
  * @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr.
@@ -295,7 +295,7 @@ export function runFilesSearch(argsList: string[], enableLineNumbers = false, ve
  * @throws {ReqError} Throws when no source files are found or no file can be analyzed.
  * @satisfies REQ-014, REQ-076, REQ-077, REQ-078, REQ-079
  */
-export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult {
+export function runSummarize(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult {
   const [base, srcDirs] = resolveProjectSrcDirs(projectBase, config);
   const files = collectSourceFiles(srcDirs, base);
   if (files.length === 0) fail("Error: no source files found in configured directories.", 1);
@@ -308,6 +308,26 @@ export function runReferences(projectBase: string, config?: UseReqConfig, verbos
   }
 }
 
+/**
+ * @brief Writes configured project references markdown to the canonical docs file.
+ * @details Reuses `runSummarize(...)` to generate the same file-structure-plus-summary markdown, resolves `<docs-dir>/REFERENCES.md` from the effective project configuration, overwrites the target file, and returns the status-only stdout `success`. Runtime is O(F log F + S) plus one file write. Side effects include filesystem writes.
+ * @param[in] projectBase {string} Candidate project root.
+ * @param[in] config {UseReqConfig | undefined} Optional preloaded configuration.
+ * @param[in] verbose {boolean} When `true`, emit per-file diagnostics to stderr during summary generation.
+ * @return {ToolResult} Successful tool result containing the status-only stdout payload.
+ * @throws {ReqError} Throws when source discovery, summary generation, or file writing fails.
+ * @satisfies REQ-293
+ */
+export function runReferences(projectBase: string, config?: UseReqConfig, verbose = false): ToolResult {
+  const base = resolveProjectBase(projectBase);
+  const effectiveConfig = config ?? loadConfig(base);
+  const docsDir = effectiveConfig["docs-dir"].replace(/[/\\]+$/, "");
+  const referencesPath = path.join(base, docsDir, "REFERENCES.md");
+  const summarizeResult = runSummarize(base, effectiveConfig, verbose);
+  fs.writeFileSync(referencesPath, summarizeResult.stdout, "utf8");
+  return ok("success\n");
+}
+
 /**
  * @brief Compresses all source files from configured source directories.
  * @details Resolves the project base, collects source files, and delegates to `compressFiles`. Runtime is O(F + S). Side effects are limited to filesystem reads and optional stderr logging.