pi-usereq 0.11.0 → 0.13.0

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);
+  }
+}

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() ?? "";
 }
 
 /**