pi-usereq 0.7.0 → 0.11.0

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

@@ -0,0 +1,211 @@
+/**
+ * @file
+ * @brief Persists prompt-command runtime state across session rebinding.
+ * @details Stores the current prompt-orchestration workflow state, the pending or active execution plan, and the latest reusable command-capable replacement-session context on `globalThis` so slash-command worktree handoff survives pi session replacement in the same host process. Runtime is O(1). Side effects are limited to process-scoped state mutation.
+ */
+
+import path from "node:path";
+import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
+
+/**
+ * @brief Represents the workflow-state domain persisted across session rebinding.
+ * @details Mirrors the prompt-orchestration states used by the status controller so the process-scoped store can remain independent from module-local controller instances. The alias is compile-time only and introduces no runtime cost.
+ */
+export type PromptCommandRuntimeWorkflowState = "idle" | "checking" | "running" | "merging" | "error";
+
+/**
+ * @brief Stores the prompt-command facts persisted across extension rebinding.
+ * @details Tracks the current workflow state plus the pending or active execution plan keyed implicitly by the surviving pi host process. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface PersistedPromptCommandRuntimeState {
+  workflowState: PromptCommandRuntimeWorkflowState;
+  pendingPromptRequest: PromptCommandExecutionPlan | undefined;
+  activePromptRequest: PromptCommandExecutionPlan | undefined;
+}
+
+/**
+ * @brief Describes the reusable command-capable session context persisted for prompt closure.
+ * @details Mirrors the minimal `ExtensionCommandContext` surface needed after prompt activation so lifecycle handlers can continue switching sessions, reading session facts, and delivering messages even when later pi lifecycle event contexts are non-command instances. The interface is compile-time only and introduces no runtime cost.
+ */
+export interface PersistedPromptCommandSessionContext {
+  cwd?: string;
+  switchSession?: (
+    sessionPath: string,
+    options?: any,
+  ) => Promise<{ cancelled?: boolean } | void> | { cancelled?: boolean } | void;
+  sendUserMessage?: (
+    content: any,
+    options?: any,
+  ) => Promise<void> | void;
+  sessionManager?: {
+    getBranch?: () => any[];
+    getCwd?: () => string;
+    getSessionDir?: () => string | undefined;
+    getSessionFile?: () => string | undefined;
+  };
+}
+
+/**
+ * @brief Defines the global property used for prompt-command runtime persistence.
+ * @details The property lives on `globalThis` because pi tears down and reloads extension modules on session switches while the host process persists. Access complexity is O(1).
+ */
+const PI_USEREQ_PROMPT_COMMAND_STATE_KEY = "__piUsereqPromptCommandRuntimeState";
+
+/**
+ * @brief Defines the global property used for reusable prompt command-context persistence.
+ * @details The property stores the latest execution-session file plus its matching command-capable context so closure handling can reuse that context after the active extension runtime is rebound. Access complexity is O(1).
+ */
+const PI_USEREQ_PROMPT_COMMAND_CONTEXT_KEY = "__piUsereqPromptCommandSessionContextState";
+
+/**
+ * @brief Returns the process-scoped prompt-command persistence store.
+ * @details Lazily initializes one mutable record that survives extension rebinds in the same pi host process. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {PersistedPromptCommandRuntimeState} Mutable persistence record.
+ */
+function getPersistedPromptCommandRuntimeStateStore(): PersistedPromptCommandRuntimeState {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqPromptCommandRuntimeState?: PersistedPromptCommandRuntimeState;
+  };
+  globalState[PI_USEREQ_PROMPT_COMMAND_STATE_KEY] ??= {
+    workflowState: "idle",
+    pendingPromptRequest: undefined,
+    activePromptRequest: undefined,
+  };
+  return globalState[PI_USEREQ_PROMPT_COMMAND_STATE_KEY]!;
+}
+
+/**
+ * @brief Returns the process-scoped reusable prompt command-context store.
+ * @details Lazily initializes one mutable record that survives extension rebinds in the same pi host process and tracks which execution-session file owns the stored command-capable context. Runtime is O(1). Side effect: initializes process-scoped state on first access.
+ * @return {{ executionSessionFile: string | undefined; sessionContext: PersistedPromptCommandSessionContext | undefined }} Mutable reusable-context record.
+ */
+function getPersistedPromptCommandSessionContextStore(): {
+  executionSessionFile: string | undefined;
+  sessionContext: PersistedPromptCommandSessionContext | undefined;
+} {
+  const globalState = globalThis as typeof globalThis & {
+    __piUsereqPromptCommandSessionContextState?: {
+      executionSessionFile: string | undefined;
+      sessionContext: PersistedPromptCommandSessionContext | undefined;
+    };
+  };
+  globalState[PI_USEREQ_PROMPT_COMMAND_CONTEXT_KEY] ??= {
+    executionSessionFile: undefined,
+    sessionContext: undefined,
+  };
+  return globalState[PI_USEREQ_PROMPT_COMMAND_CONTEXT_KEY]!;
+}
+
+/**
+ * @brief Returns a snapshot of the persisted prompt-command runtime state.
+ * @details Copies the process-scoped workflow state and request references into one detached object so callers can reason about the current persistence payload without mutating it accidentally. Runtime is O(1). No external state is mutated.
+ * @return {PersistedPromptCommandRuntimeState} Current persisted snapshot.
+ */
+export function readPersistedPromptCommandRuntimeState(): PersistedPromptCommandRuntimeState {
+  const store = getPersistedPromptCommandRuntimeStateStore();
+  return {
+    workflowState: store.workflowState,
+    pendingPromptRequest: store.pendingPromptRequest,
+    activePromptRequest: store.activePromptRequest,
+  };
+}
+
+/**
+ * @brief Replaces the persisted prompt-command runtime state.
+ * @details Writes the supplied workflow state and execution-plan references into the process-scoped store so later extension instances can recover prompt orchestration after a session switch. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @param[in] state {PersistedPromptCommandRuntimeState} Replacement persisted state.
+ * @return {void} No return value.
+ */
+export function writePersistedPromptCommandRuntimeState(
+  state: PersistedPromptCommandRuntimeState,
+): void {
+  const store = getPersistedPromptCommandRuntimeStateStore();
+  store.workflowState = state.workflowState;
+  store.pendingPromptRequest = state.pendingPromptRequest;
+  store.activePromptRequest = state.activePromptRequest;
+}
+
+/**
+ * @brief Clears the persisted prompt-command runtime state.
+ * @details Resets the process-scoped workflow state to `idle` and removes both request references so future extension instances do not inherit stale prompt orchestration. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @return {void} No return value.
+ */
+export function clearPersistedPromptCommandRuntimeState(): void {
+  writePersistedPromptCommandRuntimeState({
+    workflowState: "idle",
+    pendingPromptRequest: undefined,
+    activePromptRequest: undefined,
+  });
+  clearPersistedPromptCommandSessionContext();
+}
+
+/**
+ * @brief Replaces the reusable prompt command-capable session context.
+ * @details Associates the supplied command-capable context with one execution-session file so later lifecycle handlers can recover it after pi rebinds the active extension runtime. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @param[in] executionSessionFile {string} Execution-session file that owns the context.
+ * @param[in] sessionContext {PersistedPromptCommandSessionContext | undefined} Replacement command-capable context.
+ * @return {void} No return value.
+ */
+export function writePersistedPromptCommandSessionContext(
+  executionSessionFile: string,
+  sessionContext: PersistedPromptCommandSessionContext | undefined,
+): void {
+  const store = getPersistedPromptCommandSessionContextStore();
+  store.executionSessionFile = path.resolve(executionSessionFile);
+  store.sessionContext = sessionContext;
+}
+
+/**
+ * @brief Clears the reusable prompt command-capable session context.
+ * @details Removes the stored execution-session file and context reference so future closure handling cannot reuse stale command objects after prompt orchestration finishes. Runtime is O(1). Side effect: mutates process-scoped state.
+ * @return {void} No return value.
+ */
+export function clearPersistedPromptCommandSessionContext(): void {
+  const store = getPersistedPromptCommandSessionContextStore();
+  store.executionSessionFile = undefined;
+  store.sessionContext = undefined;
+}
+
+/**
+ * @brief Restores the reusable prompt command-capable session context for one execution-session file.
+ * @details Returns the stored command-capable context only when the supplied execution-session file matches the latest stored execution-session file. Runtime is O(1). No external state is mutated.
+ * @param[in] executionSessionFile {string | undefined} Candidate execution-session file.
+ * @return {PersistedPromptCommandSessionContext | undefined} Matching stored context or `undefined` when unavailable.
+ */
+export function readPersistedPromptCommandSessionContext(
+  executionSessionFile: string | undefined,
+): PersistedPromptCommandSessionContext | undefined {
+  if (typeof executionSessionFile !== "string" || executionSessionFile === "") {
+    return undefined;
+  }
+  const store = getPersistedPromptCommandSessionContextStore();
+  return typeof store.executionSessionFile === "string"
+    && path.resolve(store.executionSessionFile) === path.resolve(executionSessionFile)
+    ? store.sessionContext
+    : undefined;
+}
+
+/**
+ * @brief Restores persisted prompt-command runtime state for one active session file.
+ * @details Returns the persisted workflow state plus execution-plan references only when the supplied session file matches the persisted execution-session file of the pending or active plan. Runtime is O(1). No external state is mutated.
+ * @param[in] sessionFile {string | undefined} Current active session file.
+ * @return {PersistedPromptCommandRuntimeState | undefined} Matching persisted state or `undefined` when no persisted plan targets the supplied session.
+ */
+export function restorePersistedPromptCommandRuntimeStateForSession(
+  sessionFile: string | undefined,
+): PersistedPromptCommandRuntimeState | undefined {
+  if (typeof sessionFile !== "string" || sessionFile === "") {
+    return undefined;
+  }
+  const normalizedSessionFile = path.resolve(sessionFile);
+  const persistedState = readPersistedPromptCommandRuntimeState();
+  const pendingExecutionSessionFile = persistedState.pendingPromptRequest?.executionSessionFile;
+  if (typeof pendingExecutionSessionFile === "string" && path.resolve(pendingExecutionSessionFile) === normalizedSessionFile) {
+    return persistedState;
+  }
+  const activeExecutionSessionFile = persistedState.activePromptRequest?.executionSessionFile;
+  if (typeof activeExecutionSessionFile === "string" && path.resolve(activeExecutionSessionFile) === normalizedSessionFile) {
+    return persistedState;
+  }
+  return undefined;
+}

package/src/core/prompts.ts

@@ -1,52 +1,44 @@
 /**
  * @file
  * @brief Renders bundled pi-usereq prompts for the current project context.
- * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev conformance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
+ * @details Applies placeholder substitution, legacy tool-name rewrites, and conditional pi.dev governance guidance before prompt text is sent to the agent. Runtime is linear in prompt size plus replacement count. Side effects are limited to filesystem reads used for manifest checks and bundled prompt loading.
  */
 
 import fs from "node:fs";
 import path from "node:path";
 import { buildPromptReplacementPaths, type UseReqConfig } from "./config.js";
-import { readBundledPrompt } from "./resources.js";
+import { formatRuntimePathForDisplay } from "./path-context.js";
+import type {
+  PromptCommandExecutionPlan,
+  PromptCommandName,
+} from "./prompt-command-runtime.js";
+import { getPromptRequiredDocs } from "./prompt-command-runtime.js";
+import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 
 /**
  * @brief Defines regex rewrites from legacy CLI spellings to internal tool names.
  * @details The ordered replacement table converts historical `req --...` references into names exposed by the extension runtime. Application cost is O(p*r) where p is pattern count and r is prompt length.
  */
 const TOOL_REFERENCE_REPLACEMENTS: Array<[RegExp, string]> = [
-  [/`req --find`/g, "`find` tool"],
-  [/`req --files-find`/g, "`files-find` tool"],
+  [/`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"],
-  [/`req --git-check`/g, "`git-check` tool"],
-  [/`req --docs-check`/g, "`docs-check` tool"],
-  [/`req --git-wt-name`/g, "`git-wt-name` tool"],
-  [/`req --git-wt-create`/g, "`git-wt-create` tool"],
-  [/`req --git-wt-delete`/g, "`git-wt-delete` tool"],
-  [/`req --git-path`/g, "`git-path` tool"],
-  [/`req --get-base-path`/g, "`get-base-path` tool"],
-  [/\breq --find\b/g, "find tool"],
-  [/\breq --files-find\b/g, "files-find 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"],
   [/\breq --files-static-check\b/g, "files-static-check tool"],
-  [/\breq --git-check\b/g, "git-check tool"],
-  [/\breq --docs-check\b/g, "docs-check tool"],
-  [/\breq --git-wt-name\b/g, "git-wt-name tool"],
-  [/\breq --git-wt-create\b/g, "git-wt-create tool"],
-  [/\breq --git-wt-delete\b/g, "git-wt-delete tool"],
-  [/\breq --git-path\b/g, "git-path tool"],
-  [/\breq --get-base-path\b/g, "get-base-path tool"],
 ];
 
 /**
- * @brief Lists prompt names that may require pi.dev manifest conformance rules.
- * @details Only prompts that inspect or mutate source code receive the conditional conformance block. Membership checks are O(1) through the set representation.
+ * @brief Lists prompt names that may require pi.dev manifest governance rules.
+ * @details Only prompts that inspect or mutate source code receive the conditional governance block. Membership checks are O(1) through the set representation.
  */
 const PI_DEV_AWARE_PROMPT_NAMES = new Set<string>([
   "analyze",
@@ -71,27 +63,50 @@ const PI_DEV_MANIFEST_PROMPT_PATH = "docs/pi.dev/agent-document-manifest.json";
  */
 const PI_DEV_DOCS_PROMPT_PATH = "docs/pi.dev";
 /**
- * @brief Defines the injected pi.dev conformance guidance block.
- * @details The block requires manifest-first review and manifest-defined API compliance for new or modified software that interfaces with the pi.dev CLI. Construction happens once at module load. Access complexity is O(1).
- * @satisfies REQ-033, REQ-034, REQ-108
+ * @brief Stores the repository-relative base directory for pi.dev coding-agent documentation.
+ * @details Prompt guidance cites this directory when defining the authoritative extension-to-client interface contract. Lookup complexity is O(1).
+ */
+const PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH = `${PI_DEV_DOCS_PROMPT_PATH}/coding-agent-docs`;
+/**
+ * @brief Stores the repository-relative pi client source path used for interface validation guidance.
+ * @details Prompt guidance cites this directory when requiring read-only validation against the pi client implementation. Lookup complexity is O(1).
+ */
+const PI_DEV_SOURCE_PROMPT_PATH = "pi.dev-src/pi-mono";
+/**
+ * @brief Defines the injected pi.dev governance guidance block.
+ * @details The block requires read-only handling for documentation and pi client sources, manifest-first review, coding-agent-document compliance, and pi client source validation for ambiguous or bug-fix interface work. Construction happens once at module load. Access complexity is O(1).
+ * @satisfies REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
 const PI_DEV_CONFORMANCE_BLOCK = [
-  "- If the task creates or modifies software that interfaces with the pi.dev CLI, "
-    + `read \`${PI_DEV_MANIFEST_PROMPT_PATH}\` and every document path it `
-    + "references before analysis, implementation, verification, or bug fixing.",
-  `- Treat \`${PI_DEV_MANIFEST_PROMPT_PATH}\` as the authoritative API contract; `
-    + "new or modified pi.dev CLI integrations MUST comply with the APIs it "
-    + "describes.",
+  "- Treat every path under `docs/` as read-only; do NOT modify "
+    + `\`${PI_DEV_MANIFEST_PROMPT_PATH}\` or any other documentation file.`,
+  "- Treat every path under `pi.dev-src/` as read-only; do NOT modify "
+    + `\`${PI_DEV_SOURCE_PROMPT_PATH}\` or any other pi client source.`,
+  "- If the task creates or modifies software that interfaces with the "
+    + `pi.dev CLI, read \`${PI_DEV_MANIFEST_PROMPT_PATH}\` and every `
+    + "document path it references before analysis, implementation, "
+    + "verification, or bug fixing.",
+  `- Treat \`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` and documents `
+    + `referenced by \`${PI_DEV_MANIFEST_PROMPT_PATH}\` as the `
+    + "authoritative read-only interface contract; new or modified "
+    + "pi.dev CLI integrations MUST comply with the APIs they describe.",
   `- Treat manifest document paths as relative to \`${PI_DEV_DOCS_PROMPT_PATH}/\`.`,
+  "- If manifest or "
+    + `\`${PI_DEV_CODING_AGENT_DOCS_PROMPT_PATH}/\` guidance is `
+    + "ambiguous for extension-to-pi-client interface behavior, validate "
+    + `the produced source code by analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
+  "- For bug fixes or problem resolution influenced by extension-to-pi-client "
+    + "interface implementations, validate the produced source code by "
+    + `analyzing \`${PI_DEV_SOURCE_PROMPT_PATH}\`.`,
 ].join("\n");
 
 /**
- * @brief Builds the conditional pi.dev conformance block for one rendered prompt.
- * @details Emits the manifest-driven rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
+ * @brief Builds the conditional pi.dev governance block for one rendered prompt.
+ * @details Emits the manifest-driven governance rules only when the selected bundled prompt can analyze or mutate source code and the project root contains the pi.dev manifest. Time complexity O(1). No filesystem writes.
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
  * @return {string} Markdown bullet block or the empty string when injection is not applicable.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108
+ * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
 function buildPiDevConformanceBlock(promptName: string, projectBase: string): string {
   if (!PI_DEV_AWARE_PROMPT_NAMES.has(promptName)) {
@@ -105,13 +120,13 @@ function buildPiDevConformanceBlock(promptName: string, projectBase: string): st
 }
 
 /**
- * @brief Injects the pi.dev conformance block into the prompt behavior section.
+ * @brief Injects the pi.dev governance block into the prompt behavior section.
  * @details Inserts the block immediately after the `## Behavior` heading so downstream agents evaluate the rule before workflow steps. Leaves prompts unchanged when no behavior section exists or the block is already present. Time complexity O(n).
  * @param[in] text {string} Prompt markdown after placeholder replacement.
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] projectBase {string} Absolute project root used for manifest existence checks.
  * @return {string} Prompt markdown with zero or one injected conformance block.
- * @satisfies REQ-032, REQ-033, REQ-034, REQ-108
+ * @satisfies REQ-032, REQ-033, REQ-034, REQ-108, REQ-273, REQ-274, REQ-275
  */
 function injectPiDevConformanceBlock(text: string, promptName: string, projectBase: string): string {
   const block = buildPiDevConformanceBlock(promptName, projectBase);
@@ -153,30 +168,147 @@ export function applyReplacements(text: string, replacements: Record<string, str
   return updated;
 }
 
+/**
+ * @brief Builds the prompt-command execution block injected at prompt start.
+ * @details Serializes the already-completed repository validation, prompt-specific required-doc validation, worktree routing decision, and extension-owned lifecycle responsibilities so downstream agents do not repeat command-side orchestration. Time complexity is O(d) in required-doc count. No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt identifier.
+ * @param[in] executionPlan {PromptCommandExecutionPlan} Prepared command execution plan.
+ * @return {string} Markdown block or the empty string when runtime execution metadata is unavailable.
+ * @satisfies REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209
+ */
+function buildPromptExecutionBlock(
+  promptName: PromptCommandName,
+  executionPlan: PromptCommandExecutionPlan | undefined,
+): string {
+  if (!executionPlan) {
+    return "";
+  }
+  const requiredDocs = getPromptRequiredDocs(promptName);
+  const requiredDocText = requiredDocs.length === 0
+    ? "No canonical-doc precheck is required for this prompt."
+    : requiredDocs.map((requirement) => requirement.fileName).join(", ");
+  const preparedContextPath = formatRuntimePathForDisplay(executionPlan.contextPath);
+  const worktreeLine = executionPlan.worktreeDir
+    ? `3. Worktree routing already passed: created worktree-dir \`${executionPlan.worktreeDir}\` and prepared context-path \`${preparedContextPath}\`.`
+    : `3. Worktree routing already passed: worktree orchestration is disabled and context-path remains \`${preparedContextPath}\`.`;
+  return [
+    "## Extension-Orchestrated Runtime",
+    "1. Slash-command-owned git repository validation already passed before prompt dispatch.",
+    `2. Prompt-specific required-doc validation already passed: ${requiredDocText}`,
+    worktreeLine,
+    "4. The extension owns prompt-end worktree merge and fork-session retention. Do NOT repeat repository validation, canonical-doc validation, worktree creation, or merge inside this workflow.",
+  ].join("\n");
+}
+
+/**
+ * @brief Injects the prompt-command execution block near the start of the rendered prompt.
+ * @details Inserts the execution block immediately after the first level-1 heading so downstream agents evaluate extension-owned orchestration before workflow steps. Leaves prompts unchanged when no execution block is provided or when the block is already present. Time complexity O(n).
+ * @param[in] text {string} Prompt markdown after placeholder replacement.
+ * @param[in] promptName {PromptCommandName} Bundled prompt identifier.
+ * @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Prepared execution plan.
+ * @return {string} Prompt markdown with zero or one injected execution block.
+ */
+function injectPromptExecutionBlock(
+  text: string,
+  promptName: PromptCommandName,
+  executionPlan: PromptCommandExecutionPlan | undefined,
+): string {
+  const block = buildPromptExecutionBlock(promptName, executionPlan);
+  const headingMatch = text.match(/^# .*$/m);
+  if (!block || !headingMatch || text.includes(block)) {
+    return text;
+  }
+  return text.replace(headingMatch[0], `${headingMatch[0]}\n\n${block}`);
+}
+
+/**
+ * @brief Builds prompt-specific runtime placeholder replacements.
+ * @details Merges shared path substitutions with prompt-scoped runtime values for `%%ARGS%%` and `%%PROMPT%%`. Time complexity is O(g log g + s) due to delegated path replacement building, where g is guideline count and s is source-directory count. Side effects are limited to filesystem reads delegated to shared path-context helpers.
+ * @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
+ * @param[in] args {string} Raw user-supplied prompt arguments.
+ * @param[in] projectBase {string} Absolute project root used for placeholder resolution.
+ * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
+ * @return {Record<string, string>} Prompt-specific placeholder-to-value map.
+ * @satisfies REQ-002, REQ-211
+ */
+function buildPromptReplacements(
+  promptName: string,
+  args: string,
+  projectBase: string,
+  contextPath: string,
+  config: UseReqConfig,
+): Record<string, string> {
+  return {
+    ...buildPromptReplacementPaths(projectBase, contextPath, config),
+    "%%ARGS%%": args,
+    "%%PROMPT%%": promptName,
+  };
+}
+
+/**
+ * @brief Renders the bundled git instruction injected through `%%COMMIT%%`.
+ * @details Selects `resources/instructions/git_commit.md` when automatic git commit is enabled and `resources/instructions/git_read-only.md` otherwise, then applies the same runtime placeholder substitutions used by bundled prompts before returning the rendered markdown. Time complexity is O(n + g log g + s) where n is instruction size, g is guideline count, and s is source-directory count. Side effects are limited to filesystem reads.
+ * @param[in] promptName {string} Bundled prompt identifier without the `req-` prefix.
+ * @param[in] args {string} Raw user-supplied prompt arguments.
+ * @param[in] projectBase {string} Absolute project root used for placeholder resolution.
+ * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
+ * @return {string} Rendered bundled git instruction selected for the current automatic-commit mode.
+ * @satisfies REQ-211, REQ-213, REQ-214
+ */
+function renderBundledCommitInstruction(
+  promptName: string,
+  args: string,
+  projectBase: string,
+  contextPath: string,
+  config: UseReqConfig,
+): string {
+  const instruction = readBundledInstruction(
+    config.AUTO_GIT_COMMIT === "enable" ? "git_commit" : "git_read-only",
+  );
+  return applyReplacements(
+    instruction,
+    buildPromptReplacements(promptName, args, projectBase, contextPath, config),
+  );
+}
+
 /**
  * @brief Renders a bundled prompt for the current project context.
- * @details Loads the bundled markdown template, expands configuration-derived placeholders, injects conditional pi.dev conformance guidance, and rewrites legacy tool references to internal names. Time complexity O(n) relative to prompt size. No tracked files are modified.
+ * @details Loads the bundled markdown template, expands configuration-derived placeholders, injects extension-owned execution guidance plus conditional pi.dev governance guidance, expands the optional bundled commit instruction, and rewrites legacy tool references to internal names. Time complexity O(n) relative to prompt size plus delegated commit-instruction rendering. No tracked files are modified.
  * @param[in] promptName {string} Bundled prompt identifier.
  * @param[in] args {string} Raw user-supplied prompt arguments.
  * @param[in] projectBase {string} Absolute project root used for placeholder and manifest resolution.
  * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
+ * @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Optional prompt-command execution plan used for injected runtime guidance.
  * @return {string} Fully rendered prompt markdown ready for `pi.sendUserMessage(...)`.
- * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108
+ * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275
  */
 export function renderPrompt(
   promptName: string,
   args: string,
   projectBase: string,
   config: UseReqConfig,
+  executionPlan?: PromptCommandExecutionPlan,
 ): string {
+  const contextPath = executionPlan?.contextPath ?? projectBase;
   const prompt = readBundledPrompt(promptName);
   const replacements = {
-    ...buildPromptReplacementPaths(projectBase, config),
-    "%%ARGS%%": args,
+    ...buildPromptReplacements(promptName, args, projectBase, contextPath, config),
+    "%%COMMIT%%": renderBundledCommitInstruction(
+      promptName,
+      args,
+      projectBase,
+      contextPath,
+      config,
+    ),
   };
   const rendered = applyReplacements(prompt, replacements);
-  const withPiDevConformance = injectPiDevConformanceBlock(
+  const withExecutionBlock = injectPromptExecutionBlock(
     rendered,
+    promptName as PromptCommandName,
+    executionPlan,
+  );
+  const withPiDevConformance = injectPiDevConformanceBlock(
+    withExecutionBlock,
     promptName,
     projectBase,
   );