Merge branch 'main' into t3code/edf90f03

Author: subsy

src/config/index.ts

@@ -247,6 +247,8 @@ function mergeConfigs(
   if (project.progressFile !== undefined)
     merged.progressFile = project.progressFile;
   if (project.autoCommit !== undefined) merged.autoCommit = project.autoCommit;
+  if (project.commitMessageTemplate !== undefined)
+    merged.commitMessageTemplate = project.commitMessageTemplate;
   if (project.subagentTracingDetail !== undefined) {
     merged.subagentTracingDetail = project.subagentTracingDetail;
   }
@@ -703,6 +705,7 @@ export async function buildConfig(
     // CLI --prompt takes precedence over config file prompt_template
     promptTemplate: options.promptPath ?? storedConfig.prompt_template,
     autoCommit: storedConfig.autoCommit ?? false,
+    commitMessageTemplate: storedConfig.commitMessageTemplate,
   };
 }
 

src/config/schema.test.ts

@@ -522,6 +522,22 @@ describe('StoredConfigSchema', () => {
     expect(result.envPassthrough).toEqual(['MY_API_KEY']);
   });
 
+  test('accepts commitMessageTemplate as an optional string', () => {
+    const result = StoredConfigSchema.parse({
+      commitMessageTemplate: '{{taskType}}({{taskId}}): {{taskTitle}}',
+    });
+    expect(result.commitMessageTemplate).toBe('{{taskType}}({{taskId}}): {{taskTitle}}');
+  });
+
+  test('accepts empty config without commitMessageTemplate', () => {
+    const result = StoredConfigSchema.parse({});
+    expect(result.commitMessageTemplate).toBeUndefined();
+  });
+
+  test('rejects commitMessageTemplate when set to a non-string', () => {
+    expect(() => StoredConfigSchema.parse({ commitMessageTemplate: 42 })).toThrow();
+  });
+
   test('accepts top-level preflightTimeoutMs within bounds', () => {
     const result = StoredConfigSchema.parse({ preflightTimeoutMs: 60000 });
     expect(result.preflightTimeoutMs).toBe(60000);

src/config/schema.ts

@@ -154,6 +154,7 @@ export const StoredConfigSchema = z
     iterationDelay: z.number().int().min(0).max(300000).optional(),
     outputDir: z.string().optional(),
     autoCommit: z.boolean().optional(),
+    commitMessageTemplate: z.string().optional(),
 
     // Plugin configurations
     agents: z.array(AgentPluginConfigSchema).optional(),

src/config/types.ts

@@ -326,6 +326,13 @@ export interface StoredConfig {
   /** Whether to auto-commit after successful tasks */
   autoCommit?: boolean;
 
+  /**
+   * Handlebars template for auto-commit subject lines. Available variables:
+   * `{{taskId}}`, `{{taskTitle}}`, `{{taskType}}` (falls back to `chore` when
+   * the tracker omits a type). Defaults to `"{{taskType}}: {{taskId}} {{taskTitle}}"`.
+   */
+  commitMessageTemplate?: string;
+
   /** Custom prompt template path (relative to cwd or absolute) */
   prompt_template?: string;
 
@@ -398,6 +405,13 @@ export interface RalphConfig {
   /** Whether to auto-commit after successful task completion (default: false) */
   autoCommit?: boolean;
 
+  /**
+   * Handlebars template for auto-commit subject lines. When omitted, the default
+   * `"{{taskType}}: {{taskId}} {{taskTitle}}"` is used (with `taskType` falling
+   * back to `chore` when the tracker omits a type).
+   */
+  commitMessageTemplate?: string;
+
   /**
    * Optional list of task IDs to execute. When provided, only tasks with these
    * IDs will be executed, filtering out any others returned by the tracker.

src/engine/auto-commit.ts

@@ -1,8 +1,10 @@
 /**
  * ABOUTME: Auto-commit utility for committing changes after successful task completion.
- * Provides git operations to stage and commit changes when autoCommit is enabled.
+ * Provides git operations to stage and commit changes when autoCommit is enabled,
+ * plus Handlebars-based rendering of configurable commit subject templates.
  */
 
+import Handlebars from 'handlebars';
 import { runProcess } from '../utils/process.js';
 
 /**
@@ -21,6 +23,94 @@ export interface AutoCommitResult {
   error?: string;
 }
 
+/**
+ * Default commit subject template used when the user has not set
+ * `commitMessageTemplate` in their config. Uses the tracker-reported task type
+ * (with a `chore` fallback) so commits look Conventional-Commits-shaped without
+ * mis-labeling everything as `feat:`.
+ */
+export const DEFAULT_COMMIT_MESSAGE_TEMPLATE = '{{taskType}}: {{taskId}} {{taskTitle}}';
+
+/**
+ * Fallback used when a task's `type` is missing or empty so user templates
+ * always render to a non-empty subject.
+ */
+export const DEFAULT_TASK_TYPE = 'chore';
+
+/**
+ * Inputs for {@link renderCommitMessage}.
+ */
+export interface CommitMessageContext {
+  taskId: string;
+  taskTitle: string;
+  taskType?: string;
+}
+
+/**
+ * Result of rendering a commit message template.
+ */
+export interface RenderCommitMessageResult {
+  /** The rendered commit subject. Always non-empty. */
+  message: string;
+  /**
+   * True when the caller-supplied template rendered to an empty/whitespace
+   * string (or failed to compile) and we fell back to the default template.
+   */
+  usedFallback: boolean;
+  /** Compile/render error message when {@link usedFallback} is true. */
+  fallbackReason?: string;
+}
+
+function buildHandlebarsContext(ctx: CommitMessageContext): Record<string, string> {
+  const type = ctx.taskType?.trim();
+  return {
+    taskId: ctx.taskId,
+    taskTitle: ctx.taskTitle,
+    taskType: type && type.length > 0 ? type : DEFAULT_TASK_TYPE,
+  };
+}
+
+function compileAndRender(template: string, ctx: Record<string, string>): string {
+  const compiled = Handlebars.compile(template, { noEscape: true, strict: false });
+  return compiled(ctx).trim();
+}
+
+/**
+ * Render a Handlebars commit subject template. Falls back to the default
+ * template when the user-supplied template renders empty/whitespace-only or
+ * throws while compiling.
+ */
+export function renderCommitMessage(
+  template: string | undefined,
+  ctx: CommitMessageContext
+): RenderCommitMessageResult {
+  const handlebarsCtx = buildHandlebarsContext(ctx);
+  const effectiveTemplate = template ?? DEFAULT_COMMIT_MESSAGE_TEMPLATE;
+
+  let rendered: string;
+  try {
+    rendered = compileAndRender(effectiveTemplate, handlebarsCtx);
+  } catch (err) {
+    const fallback = compileAndRender(DEFAULT_COMMIT_MESSAGE_TEMPLATE, handlebarsCtx);
+    return {
+      message: fallback,
+      usedFallback: true,
+      fallbackReason: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  if (rendered.length === 0) {
+    const fallback = compileAndRender(DEFAULT_COMMIT_MESSAGE_TEMPLATE, handlebarsCtx);
+    return {
+      message: fallback,
+      usedFallback: true,
+      fallbackReason: 'template rendered to empty string',
+    };
+  }
+
+  return { message: rendered, usedFallback: false };
+}
+
 /**
  * Check if there are uncommitted changes in the working directory.
  * Throws if git status cannot be determined (not a git repo, git not installed, etc.).
@@ -34,13 +124,12 @@ export async function hasUncommittedChanges(cwd: string): Promise<boolean> {
 }
 
 /**
- * Stage all changes and create a commit with a standardized message format.
- * Returns the result of the operation including commit SHA on success.
+ * Stage all changes and create a commit using the supplied subject line.
+ * The caller is responsible for rendering any template — see {@link renderCommitMessage}.
  */
 export async function performAutoCommit(
   cwd: string,
-  taskId: string,
-  taskTitle: string
+  commitMessage: string
 ): Promise<AutoCommitResult> {
   // Check for uncommitted changes first
   let hasChanges: boolean;
@@ -68,8 +157,7 @@ export async function performAutoCommit(
     };
   }
 
-  // Create commit with standardized message
-  const commitMessage = `feat: ${taskId} - ${taskTitle}`;
+  // Create commit with supplied message
   const commitResult = await runProcess(
     'git',
     ['commit', '-m', commitMessage],

src/engine/index.ts

@@ -56,7 +56,7 @@ import {
 } from '../plugins/agents/usage.js';
 import { updateSessionIteration, updateSessionStatus, updateSessionMaxIterations } from '../session/index.js';
 import { saveIterationLog, buildSubagentTrace, getRecentProgressSummary, getCodebasePatternsForPrompt } from '../logs/index.js';
-import { performAutoCommit } from './auto-commit.js';
+import { performAutoCommit, renderCommitMessage } from './auto-commit.js';
 import type { AgentSwitchEntry } from '../logs/index.js';
 import { renderPrompt } from '../templates/index.js';
 import { appendWithCharLimit as appendWithSharedCharLimit } from '../utils/buffer-limits.js';
@@ -2225,7 +2225,17 @@ export class ExecutionEngine {
    */
   private async handleAutoCommit(task: TrackerTask, iteration: number): Promise<void> {
     try {
-      const result = await performAutoCommit(this.config.cwd, task.id, task.title);
+      const rendered = renderCommitMessage(this.config.commitMessageTemplate, {
+        taskId: task.id,
+        taskTitle: task.title,
+        taskType: task.type,
+      });
+      if (rendered.usedFallback) {
+        console.warn(
+          `[auto-commit] commitMessageTemplate fell back to the default for task ${task.id}: ${rendered.fallbackReason}`
+        );
+      }
+      const result = await performAutoCommit(this.config.cwd, rendered.message);
       if (result.committed) {
         this.emit({
           type: 'task:auto-committed',
@@ -2234,6 +2244,7 @@ export class ExecutionEngine {
           iteration,
           commitMessage: result.commitMessage!,
           commitSha: result.commitSha,
+          templateFallbackReason: rendered.usedFallback ? rendered.fallbackReason : undefined,
         });
       } else if (result.error) {
         this.emit({

src/engine/types.ts

@@ -479,6 +479,13 @@ export interface TaskAutoCommittedEvent extends EngineEventBase {
   commitMessage: string;
   /** Short SHA of the commit (if available) */
   commitSha?: string;
+  /**
+   * Populated when a configured `commitMessageTemplate` failed to render
+   * (Handlebars error or empty/whitespace result) and the engine fell back
+   * to the default template. Always undefined when no template was set or
+   * the template rendered cleanly.
+   */
+  templateFallbackReason?: string;
 }
 
 /**