execute

name	execute
description	读取 task 文档，按 task-id 执行 Scope 内变更，生成可审计 execute 文档

Execute — 任务执行与记录

本 Skill 负责：

• 读取 task 文档，按 task-id 执行 Scope 内变更
• 生成可审计 execute 文档（包含 Commands/Assertions/Evidence）
• 作为审计与回归依据

本 Skill 仅可手动触发。

执行过程中：

• 禁止超出 Task 定义的 Scope 进行变更
• 禁止修改 Task 文档本身
• 禁止生成 patch / diff / PR / git 命令

允许读取： - `docs/*-design.md` # 最新全局设计基线 - `docs/features/*.md` # 既有功能规格，只读 - `docs/tasks/*.md` # 既有任务文档，只读 - `docs/executes/*.md` # 既有执行记录，只读 - `templates/feature.md` # 插件 Feature 模板 - `templates/tasks.md` # 插件 Tasks 模板 - `templates/execute.md` # 插件 Execute 模板

禁止修改：

• docs/*-design.md # 全局设计基线，只读
• docs/features/*.md # 既有功能规格，只读
• docs/tasks/*.md # 既有任务文档，只读

允许写入：

• docs/executes/*.md # 执行记录，可追加

---

输入前提（Preconditions）

触发本 Skill 前，必须满足：

• 已存在 docs/tasks/<task-file>.md
• 知道要执行的 <task-id>

---

流程（Process）

1) 读取 Task 文档

• 打开 docs/tasks/<task-file>.md
• 读取 Execution Timeline 表，确认 <task-id> 存在
• 定位到对应段落：## Task <task-id>: ...
  • 只接受精确匹配 ## Task {{task-id}}:，不得模糊匹配，避免错段落

2) 提取执行约束与验收信息

从该 Task 段落提取：

• 关联条目（Refs）
• Scope：Allowed / Forbidden / Out of scope
• Acceptance：Commands / Assertions / Evidence（期望）
• 依赖与风险（Deps/Risks/Rollback）

3) 执行前检查（Pre-flight）

• 生成环境快照（必须写入 execute 文档）：
  • repo/workspace、branch、base commit、working tree clean/dirty、OS、toolchain 版本、关键配置（打码）
• Scope 强制检查：
  • 仅允许修改 Allowed 指定的文件/目录/模块
  • Forbidden/Out of scope 命中的任何变更：立即停止，标记 FAIL，并在 Notes 写明原因与建议拆新 Task

4) 按 Scope 执行变更

• 变更必须最小化，仅为满足该 Task 的 Acceptance
• 若发现必须额外改动才能修复：
  • 不得擅自扩 Scope
  • 在 execute 的 Notes/Next Actions 中提出"需新增 Task"的建议

5) 运行验收（Acceptance Run）

• 必须执行该 Task 的 Acceptance 命令（Commands）
• 记录：
  • 实际运行命令（按顺序）
  • 关键断言是否满足（Assertions）
  • 输出摘要（Output Summary）
  • 证据（Evidence：日志片段/截图路径/PR/commit）

6) 生成 Execute 文档（Template Fill）

• 只能使用 templates/execute.md
• References 必须包含（最少）：
  • Design: <latest design filename>
  • Tasks: docs/tasks/<task-file>.md
  • Related Feat: ...（若 task refs 指向）
  • Related Execute: ...（如本次涉及对齐历史冲突）
• Result：
  • PASS：所有 Assertions 满足
  • FAIL：任一 Assertions 不满足或发生 Scope 越界风险

---

输出（Output）

• 生成：docs/executes/YYYY-MM-DD-HH-MM-<task-name>-<task-id>.md

命名规则：

• <task-name>：从 Task 标题（## Task <id>: ...）提取，转为 kebab-case（小写+短横线）

---

失败处理（Failure Modes）

• 找不到 templates/execute.md：停止并报告错误
• 找不到 docs/tasks/<task-file>.md：停止并报告错误
• 找不到对应 Task <task-id> 段落：停止并报告错误
• 发生 Scope 越界：必须 FAIL，且给出 rollback/next actions（不得继续扩改）

---

额外建议（Strongly Recommended）

为了让 Scope 检查更"机械化"、更不易越界，建议在 tasks 模板中把 Allowed/Forbidden 写成"目录/文件白名单与黑名单"。

示例（推荐写法）：

• Allowed：
  • internal/foo/**
  • cmd/bar/**
  • configs/app.yaml（如需）
• Forbidden：
  • go.mod
  • go.sum
  • docs/*-design.md
  • templates/**
  • docs/features/**
  • docs/tasks/**（execute 阶段禁止改 tasks 文档本身）
• Out of scope：
  • "任何新增公共 API"
  • "任何跨模块重构"
  • "任何数据迁移（除非明确写入 Allowed 与 Rollback）"