pi-usereq 0.11.0 → 0.12.0

package/src/core/prompt-command-runtime.ts

@@ -1,7 +1,7 @@
 /**
  * @file
- * @brief Implements prompt-command preflight and worktree orchestration.
- * @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization with restored-session transcript preservation, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
+ * @brief Implements bundled prompt-command preflight and worktree orchestration.
+ * @details Centralizes prompt-template-backed `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, reusable transcript-preservation plus session-restoration helpers, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success stash-assisted fast-forward merge finalization, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, stash-stack mutation, and filesystem reads and writes.
  */
 
 import fs from "node:fs";
@@ -19,10 +19,7 @@ import {
   logDebugPromptWorkflowEvent,
   type DebugWorkflowState,
 } from "./debug-runtime.js";
-import {
-  PROMPT_COMMAND_NAMES,
-  type PromptCommandName,
-} from "./prompt-command-catalog.js";
+import { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
   isSameOrAncestorPath,
   normalizeRelativeDirContract,
@@ -483,9 +480,9 @@ function readPromptSessionJsonLines(
  * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original and execution session files must be synchronized.
  * @return {void} No return value.
  * @throws {ReqError} Throws when either session file is unreadable or when appended execution records are not persisted to the original session file.
- * @satisfies REQ-208
+ * @satisfies REQ-208, REQ-307
  */
-function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void {
+export function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void {
   const normalizedOriginalSessionFile = path.resolve(plan.originalSessionFile);
   const normalizedExecutionSessionFile = path.resolve(plan.executionSessionFile);
   if (normalizedOriginalSessionFile === normalizedExecutionSessionFile) {
@@ -829,9 +826,6 @@ const PROMPT_REQUIRED_DOCS: Record<PromptCommandName, readonly PromptRequiredDoc
     { fileName: "WORKFLOW.md", promptCommand: "/req-workflow" },
     { fileName: "REFERENCES.md", promptCommand: "/req-references" },
   ],
-  references: [
-    { fileName: "REQUIREMENTS.md", promptCommand: "/req-write" },
-  ],
   renumber: [
     { fileName: "REQUIREMENTS.md", promptCommand: "/req-write" },
     { fileName: "WORKFLOW.md", promptCommand: "/req-workflow" },
@@ -855,6 +849,166 @@ function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync
   });
 }
 
+/**
+ * @brief Lists tracked `base-path` status rows that require stash-assisted merge handling.
+ * @details Executes `git status --porcelain`, retains only tracked rows whose index or worktree slot reports a change, and excludes untracked or ignored rows because the required `git stash` command does not preserve them. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include process spawning.
+ * @param[in] basePath {string} Restored project base path.
+ * @return {string[]} Tracked status rows requiring stash-assisted merge handling.
+ * @throws {ReqError} Throws when git status cannot be read from `basePath`.
+ * @satisfies REQ-291
+ */
+function listPromptTrackedBasePathChanges(basePath: string): string[] {
+  const statusResult = runCapture(["git", "status", "--porcelain"], basePath);
+  if (statusResult.error || statusResult.status !== 0) {
+    throw new ReqError("ERROR: Unable to inspect base-path changes before merge.", 1);
+  }
+  return statusResult.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== "")
+    .filter((line) => {
+      const statusCode = line.slice(0, 2);
+      if (statusCode === "??" || statusCode === "!!") {
+        return false;
+      }
+      const indexStatus = statusCode[0] ?? " ";
+      const worktreeStatus = statusCode[1] ?? " ";
+      return indexStatus !== " " || worktreeStatus !== " ";
+    });
+}
+
+/**
+ * @brief Executes the successful-closure merge sequence from restored `base-path`.
+ * @details Detects tracked staged or unstaged `base-path` changes, wraps the existing fast-forward merge in `git stash` and `git stash pop` when required, preserves the direct merge path when no tracked changes exist, emits a warning-only result after successful local-change restoration, and writes one merge-finalization debug entry when enabled. Runtime is dominated by up to four git subprocesses plus O(n) status parsing. Side effects include stash-stack mutation, branch merge attempts, and optional debug-log writes.
+ * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose branch should be merged.
+ * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
+ * @return {{ mergeAttempted: boolean; mergeSucceeded: boolean; errorMessage?: string; warningMessage?: string }} Merge-attempt facts plus optional warning text.
+ * @satisfies REQ-208, REQ-245, REQ-291, REQ-292
+ */
+function finalizePromptCommandMerge(
+  plan: PromptCommandExecutionPlan,
+  debugOptions?: PromptCommandDebugOptions,
+): {
+  mergeAttempted: boolean;
+  mergeSucceeded: boolean;
+  errorMessage?: string;
+  warningMessage?: string;
+} {
+  const worktreeDir = plan.worktreeDir ?? plan.branchName;
+  const mergeLogInput = {
+    worktree_dir: worktreeDir,
+    branch_name: plan.branchName,
+  };
+  let trackedStatusLines: string[];
+  try {
+    trackedStatusLines = listPromptTrackedBasePathChanges(plan.basePath);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (debugOptions) {
+      logDebugPromptEvent(
+        plan.basePath,
+        debugOptions.config,
+        debugOptions.workflowState,
+        plan.promptName,
+        "merge",
+        mergeLogInput,
+        {
+          success: false,
+          merge_attempted: false,
+          error: errorMessage,
+        },
+        true,
+      );
+    }
+    return {
+      mergeAttempted: false,
+      mergeSucceeded: false,
+      errorMessage,
+    };
+  }
+  const usedStash = trackedStatusLines.length > 0;
+  let stashStatus: number | null | undefined;
+  if (usedStash) {
+    const stashResult = runCapture(["git", "stash"], plan.basePath);
+    stashStatus = stashResult.status;
+    if (stashResult.error || stashResult.status !== 0) {
+      const errorMessage = `ERROR: Unable to stash base-path changes before merge for worktree ${worktreeDir}.`;
+      if (debugOptions) {
+        logDebugPromptEvent(
+          plan.basePath,
+          debugOptions.config,
+          debugOptions.workflowState,
+          plan.promptName,
+          "merge",
+          {
+            ...mergeLogInput,
+            used_stash: true,
+            tracked_change_count: trackedStatusLines.length,
+          },
+          {
+            success: false,
+            merge_attempted: false,
+            error: errorMessage,
+            stash_status: stashStatus,
+          },
+          true,
+        );
+      }
+      return {
+        mergeAttempted: false,
+        mergeSucceeded: false,
+        errorMessage,
+      };
+    }
+  }
+  const mergeResult = runCapture(
+    ["git", "merge", "--ff-only", plan.branchName],
+    plan.basePath,
+  );
+  const mergeSucceeded = !mergeResult.error && mergeResult.status === 0;
+  const errorMessage = mergeSucceeded
+    ? undefined
+    : `ERROR: Fast-forward merge failed for worktree ${worktreeDir}.`;
+  let stashPopStatus: number | null | undefined;
+  let warningMessage: string | undefined;
+  if (usedStash) {
+    const stashPopResult = runCapture(["git", "stash", "pop"], plan.basePath);
+    stashPopStatus = stashPopResult.status;
+    if (mergeSucceeded) {
+      warningMessage = "WARNING: Restored base-path changes after merge; base-path is not clean.";
+    }
+  }
+  if (debugOptions) {
+    logDebugPromptEvent(
+      plan.basePath,
+      debugOptions.config,
+      debugOptions.workflowState,
+      plan.promptName,
+      "merge",
+      {
+        ...mergeLogInput,
+        used_stash: usedStash,
+        tracked_change_count: trackedStatusLines.length,
+      },
+      {
+        success: mergeSucceeded,
+        merge_attempted: true,
+        error: errorMessage,
+        warning: warningMessage,
+        stash_status: stashStatus,
+        stash_pop_status: stashPopStatus,
+      },
+      !mergeSucceeded,
+    );
+  }
+  return {
+    mergeAttempted: true,
+    mergeSucceeded,
+    errorMessage,
+    warningMessage,
+  };
+}
+
 /**
  * @brief Stores or clears the prompt-command post-create test hook.
  * @details Enables deterministic simulation of post-create worktree verification failures without altering production control flow. Runtime is O(1). Side effect: mutates module-local test state.
@@ -950,15 +1104,15 @@ function throwPromptGitStatusError(): never {
 }
 
 /**
- * @brief Runs prompt-command-owned git validation and returns the runtime git root.
- * @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
+ * @brief Runs slash-command-owned git validation and returns the runtime git root.
+ * @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence for bundled prompt commands and `req-references` without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
  * @param[in] projectBase {string} Absolute current project base.
  * @param[in] config {UseReqConfig | undefined} Optional effective project configuration used to ignore extension-owned debug-log artifacts.
  * @return {string} Absolute runtime git root.
  * @throws {ReqError} Throws the canonical prompt-command git-preflight error on any validation failure.
  * @satisfies REQ-200, REQ-220
  */
-function validatePromptGitState(projectBase: string, config?: UseReqConfig): string {
+export function validatePromptGitState(projectBase: string, config?: UseReqConfig): string {
   const gitPath = resolveRuntimeGitPath(projectBase);
   if (!gitPath) {
     throwPromptGitStatusError();
@@ -1280,9 +1434,9 @@ function createPromptWorktree(
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
  * @return {void} No return value.
  * @throws {ReqError} Throws when cleanup cannot remove the worktree and branch fully.
- * @satisfies REQ-208, REQ-220, REQ-245
+ * @satisfies REQ-208, REQ-220, REQ-245, REQ-309
  */
-function deletePromptWorktree(
+export function deletePromptWorktree(
   basePath: string,
   worktreeDir: string,
   worktreeRootPath: string,
@@ -1691,12 +1845,12 @@ export async function abortPromptCommandExecution(
 
 /**
  * @brief Finalizes one matched successful worktree-backed prompt execution.
- * @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, executes the stash-assisted fast-forward merge sequence from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, stash-stack mutation, worktree deletion, and optional debug-log writes.
  * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
  * @param[in] ctx {PromptCommandSessionContext | undefined} Optional prompt-command context.
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
- * @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
- * @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282
+ * @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; warningMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
+ * @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282, REQ-291, REQ-292
  */
 export async function finalizePromptCommandExecution(
   plan: PromptCommandExecutionPlan,
@@ -1707,6 +1861,7 @@ export async function finalizePromptCommandExecution(
   mergeSucceeded: boolean;
   cleanupSucceeded: boolean;
   errorMessage?: string;
+  warningMessage?: string;
   activeContext?: PromptCommandSessionContext;
 }> {
   let activeContext = ctx;
@@ -1749,32 +1904,14 @@ export async function finalizePromptCommandExecution(
       activeContext,
     };
   }
-  const mergeResult = runCapture(
-    ["git", "merge", "--ff-only", plan.branchName],
-    plan.basePath,
-  );
-  const mergeSucceeded = !mergeResult.error && mergeResult.status === 0;
-  const errorMessage = mergeSucceeded
-    ? undefined
-    : `ERROR: Fast-forward merge failed for worktree ${plan.worktreeDir}.`;
-  if (debugOptions) {
-    logDebugPromptEvent(
-      plan.basePath,
-      debugOptions.config,
-      debugOptions.workflowState,
-      plan.promptName,
-      "merge",
-      { worktree_dir: plan.worktreeDir, branch_name: plan.branchName },
-      { success: mergeSucceeded, error: errorMessage },
-      !mergeSucceeded,
-    );
-  }
-  if (!mergeSucceeded) {
+  const mergeFinalization = finalizePromptCommandMerge(plan, debugOptions);
+  if (!mergeFinalization.mergeSucceeded) {
     return {
-      mergeAttempted: true,
+      mergeAttempted: mergeFinalization.mergeAttempted,
       mergeSucceeded: false,
       cleanupSucceeded: true,
-      errorMessage,
+      errorMessage: mergeFinalization.errorMessage,
+      warningMessage: mergeFinalization.warningMessage,
       activeContext,
     };
   }
@@ -1788,17 +1925,19 @@ export async function finalizePromptCommandExecution(
     );
   } catch {
     return {
-      mergeAttempted: true,
+      mergeAttempted: mergeFinalization.mergeAttempted,
       mergeSucceeded: true,
       cleanupSucceeded: false,
       errorMessage: `ERROR: Unable to remove worktree or branch ${plan.worktreeDir}.`,
+      warningMessage: mergeFinalization.warningMessage,
       activeContext,
     };
   }
   return {
-    mergeAttempted: true,
+    mergeAttempted: mergeFinalization.mergeAttempted,
     mergeSucceeded: true,
     cleanupSucceeded: true,
+    warningMessage: mergeFinalization.warningMessage,
     activeContext,
   };
 }

package/src/core/prompts.ts

@@ -22,14 +22,12 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 const TOOL_REFERENCE_REPLACEMENTS: Array<[RegExp, string]> = [
   [/`req --find`/g, "`search` tool"],
   [/`req --files-find`/g, "`files-search` tool"],
-  [/`req --references`/g, "`references` tool"],
   [/`req --compress`/g, "`compress` tool"],
   [/`req --tokens`/g, "`tokens` tool"],
   [/`req --static-check`/g, "`static-check` tool"],
   [/`req --files-static-check`/g, "`files-static-check` tool"],
   [/\breq --find\b/g, "search tool"],
   [/\breq --files-find\b/g, "files-search tool"],
-  [/\breq --references\b/g, "references tool"],
   [/\breq --compress\b/g, "compress tool"],
   [/\breq --tokens\b/g, "tokens tool"],
   [/\breq --static-check\b/g, "static-check tool"],

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

@@ -0,0 +1,175 @@
+/**
+ * @file
+ * @brief Implements the specialized `req-references` slash-command workflow.
+ * @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
+ */
+
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import type { UseReqConfig } from "./config.js";
+import { ReqError } from "./errors.js";
+import { validatePromptGitState } from "./prompt-command-runtime.js";
+import { runReferences } from "./tool-runner.js";
+
+/**
+ * @brief Declares the fixed slash-command description for `req-references`.
+ * @details Preserves the legacy human-facing command label while the runtime implementation no longer depends on a bundled prompt Markdown file. Access complexity is O(1).
+ */
+export const REQ_REFERENCES_COMMAND_DESCRIPTION = "Write a REFERENCES.md using the project's source code";
+
+/**
+ * @brief Declares the fixed git commit message used by `req-references`.
+ * @details Keeps the commit payload deterministic so downstream tooling and tests can assert the exact commit contract without parsing prompt templates. Access complexity is O(1).
+ */
+export const REQ_REFERENCES_COMMIT_MESSAGE = "docs(references): Update REFERENCES.md document. [useReq]";
+
+/**
+ * @brief Describes the prepared execution facts for one `req-references` run.
+ * @details Stores the validated project base, resolved git root, target references path, and fixed commit message needed by the specialized direct-write workflow. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface ReqReferencesCommandPlan {
+  basePath: string;
+  gitPath: string;
+  referencesPath: string;
+  commitMessage: string;
+}
+
+/**
+ * @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 Builds the set of git-status paths ignored for cleanliness checks.
+ * @details Reuses the configured debug-log path exception already honored by prompt-command git validation so extension-owned debug artifacts do not block `req-references` execution or post-commit cleanliness verification. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] projectBase {string} Absolute project base path.
+ * @param[in] gitRoot {string} Absolute git root path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {Set<string>} Slash-normalized relative paths ignored during git-status evaluation.
+ */
+function buildIgnoredGitStatusPaths(
+  projectBase: string,
+  gitRoot: string,
+  config: UseReqConfig,
+): Set<string> {
+  const ignoredStatusPaths = new Set<string>();
+  const configuredLogPath = path.isAbsolute(config.DEBUG_LOG_FILE)
+    ? path.normalize(config.DEBUG_LOG_FILE)
+    : path.resolve(projectBase, config.DEBUG_LOG_FILE);
+  const relativeLogPath = path.relative(gitRoot, configuredLogPath);
+  if (relativeLogPath !== "" && !relativeLogPath.startsWith("..") && !path.isAbsolute(relativeLogPath)) {
+    ignoredStatusPaths.add(relativeLogPath.split(path.sep).join("/"));
+  }
+  return ignoredStatusPaths;
+}
+
+/**
+ * @brief Lists residual git-status rows after ignored extension-owned paths are filtered out.
+ * @details Executes `git status --porcelain`, drops the configured debug-log path when present inside the active repository, and returns all remaining staged or unstaged rows used for post-commit cleanliness verification. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include subprocess creation.
+ * @param[in] projectBase {string} Absolute project base path.
+ * @param[in] gitRoot {string} Absolute git root path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {string[]} Residual status rows after ignored paths are removed.
+ * @throws {ReqError} Throws when git status cannot be inspected.
+ */
+function listResidualGitStatusLines(
+  projectBase: string,
+  gitRoot: string,
+  config: UseReqConfig,
+): string[] {
+  const statusResult = runCapture(["git", "status", "--porcelain"], gitRoot);
+  if (statusResult.error || statusResult.status !== 0) {
+    throw new ReqError("ERROR: Unable to inspect git repository cleanliness after req-references commit.", 1);
+  }
+  const ignoredStatusPaths = buildIgnoredGitStatusPaths(projectBase, gitRoot, config);
+  return statusResult.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== "")
+    .filter((line) => {
+      const statusPath = line.slice(3).split(" -> ").at(-1)?.split(path.sep).join("/") ?? "";
+      return !ignoredStatusPaths.has(statusPath);
+    });
+}
+
+/**
+ * @brief Converts one absolute repository path into the preferred git-add target syntax.
+ * @details Emits a slash-normalized relative path when the target is inside the git root and falls back to the absolute path otherwise, preserving deterministic add semantics across nested project-base layouts. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] gitRoot {string} Absolute git root path.
+ * @param[in] absolutePath {string} Absolute path to stage.
+ * @return {string} Relative or absolute git-add target path.
+ */
+function getGitAddTargetPath(gitRoot: string, absolutePath: string): string {
+  const relativePath = path.relative(gitRoot, absolutePath);
+  if (relativePath === "" || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return absolutePath;
+  }
+  return relativePath.split(path.sep).join("/");
+}
+
+/**
+ * @brief Prepares the specialized `req-references` execution plan.
+ * @details Reuses slash-command-owned git validation, resolves the configured references document path, and returns the fixed commit metadata consumed by the direct-write workflow. Runtime is dominated by git validation subprocesses. Side effects include subprocess creation delegated through `validatePromptGitState(...)`.
+ * @param[in] projectBase {string} Absolute project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {ReqReferencesCommandPlan} Prepared execution plan for direct references regeneration.
+ * @throws {ReqError} Throws when git validation fails.
+ * @satisfies REQ-200, REQ-299
+ */
+export function prepareReqReferencesCommandExecution(
+  projectBase: string,
+  config: UseReqConfig,
+): ReqReferencesCommandPlan {
+  const basePath = path.resolve(projectBase);
+  const gitPath = validatePromptGitState(basePath, config);
+  const docsDir = config["docs-dir"].replace(/[/\\]+$/, "");
+  return {
+    basePath,
+    gitPath,
+    referencesPath: path.join(basePath, docsDir, "REFERENCES.md"),
+    commitMessage: REQ_REFERENCES_COMMIT_MESSAGE,
+  };
+}
+
+/**
+ * @brief Executes the specialized `req-references` direct-write workflow.
+ * @details Regenerates `REFERENCES.md` through the same source-summary path used by the `references` tool, stages only the target file, creates the fixed-message commit, and verifies that no residual git-status rows remain after ignored extension-owned debug artifacts are filtered out. Runtime is dominated by summary generation plus three git subprocesses. Side effects include documentation writes, index mutation, commit creation, and subprocess creation.
+ * @param[in] plan {ReqReferencesCommandPlan} Prepared direct-write execution plan.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {void} No return value.
+ * @throws {ReqError} Throws when reference generation, staging, commit creation, or cleanliness verification fails.
+ * @satisfies REQ-300, REQ-301, REQ-302, REQ-303
+ */
+export function executeReqReferencesCommandExecution(
+  plan: ReqReferencesCommandPlan,
+  config: UseReqConfig,
+): void {
+  runReferences(plan.basePath, config);
+  const addTargetPath = getGitAddTargetPath(plan.gitPath, plan.referencesPath);
+  const addResult = runCapture(["git", "add", "--", addTargetPath], plan.gitPath);
+  if (addResult.error || addResult.status !== 0) {
+    const diagnostic = addResult.stderr.trim() || addResult.error?.message || "unknown error";
+    throw new ReqError(`ERROR: git add failed for ${addTargetPath}: ${diagnostic}`, 1);
+  }
+  const commitResult = runCapture(["git", "commit", "-m", plan.commitMessage], plan.gitPath);
+  if (commitResult.error || commitResult.status !== 0) {
+    const diagnostic = commitResult.stderr.trim()
+      || commitResult.stdout.trim()
+      || commitResult.error?.message
+      || "unknown error";
+    throw new ReqError(`ERROR: git commit failed: ${diagnostic}`, 1);
+  }
+  const residualStatusLines = listResidualGitStatusLines(plan.basePath, plan.gitPath, config);
+  if (residualStatusLines.length > 0) {
+    throw new ReqError("ERROR: Git repository is not clean after req-references commit.", 1);
+  }
+}