Genarrative/docs/technical/TASK_AUTO_COMMIT_WORKFLOW_2026-04-20.md

任务完成自动提交工作流（2026-04-20）

1. 目标

为避免“任务已完成但改动长期停留在工作区”与“提交时把无关改动一并打包”的问题，仓库补充一条统一工作流：

1. 当任务明确完成时，立即执行一次提交。
2. 只提交当前任务相关文件。
3. 提交信息使用中文简洁摘要。
4. 不依赖 git hook 或后台自动监听。

2. 实现方式

新增脚本：

• scripts/commit-task.mjs

职责：

1. 接收提交信息 -m/--message
2. 接收本次任务要提交的文件列表
3. 先检查这些文件是否确实存在未提交改动
4. 只暂存传入文件
5. 只在存在暂存内容时执行提交

3. 使用方式

命令格式：

node scripts/commit-task.mjs -m "中文提交摘要" <file...>

示例：

node scripts/commit-task.mjs \
  -m "补充任务完成后自动提交协作约定" \
  docs/experience/PROJECT_WORK_EXPERIENCE_PLAYBOOK.md \
  docs/experience/README.md

4. 行为约束

1. 不传 -m 会直接失败。
2. 不传文件列表会直接失败。
3. 指定文件没有改动时不会创建空提交。
4. 脚本不会自动把未指定文件加入提交。
5. 脚本不做 amend，不改写历史。
6. 即使索引里已经有其他已暂存文件，脚本也只会提交本次显式传入的文件。

5. 适用范围

适用于：

1. 单任务完成后的常规提交
2. 工作区存在其他无关改动时的定向提交
3. 需要明确控制提交边界的日常开发

不适用于：

1. 需要 squash 或改写历史的场景
2. 需要交互式挑选 hunk 的场景
3. 无法清晰界定当前任务文件边界的场景

6. 当前协作约定

默认规则：

1. 用户明确表示任务完成，或直接要求提交时，优先使用这条工作流。
2. 若当前任务文件边界清晰，则直接提交。
3. 若边界不清晰，则先停下并说明风险，不强行提交。

7. 验证

当前已补：

1. scripts/commit-task.test.ts
2. 覆盖“只提交指定文件，保留未指定改动在工作区”的核心行为
3. 覆盖“已有其他 staged 改动时不混入当前提交”的边界行为