ln-401-task-executor

**路径：**文件路径（references/、../ln-*）相对于此技能目录。

实现任务执行器

**类型：**L3 Worker

根据任务描述和关联指南，执行一项从 Todo 到 To Review 的实现（或重构）任务。

目的与范围

• 只处理选定的一项任务；绝不触碰其他任务。
• 遵循任务的 Technical Approach/计划/AC；应用 KISS/YAGNI 和指南中的模式。
• 更新此任务的跟踪器/看板：Todo -> In Progress -> To Review。
• 运行类型检查/代码检查；根据任务说明更新文档/测试/配置。
• 不适用于测试任务（标签为「tests」的任务交给 ln-404-test-executor）。

**Hex MCP 加速（如果可用）：**读取大型代码文件前，使用范围精确的 inspect_path(path=<relevant dir>) 和 outline(file_path)；除非有意需要，否则避免对仓库根目录执行通配符清单。搜索/发现时先使用 grep_search(output_mode="summary")，只有在需要用于后续编辑的标准代码块时，才升级为 output_mode="content", edit_ready=true；仅在明确作为最后手段时使用 allow_large_output=true。在发现模式下使用 read_file() 获取结构和指定范围；需要为后续编辑获取 revision 和校验和时，先使用 read_file(edit_ready=true, verbosity="full") 刷新该文件。编辑现有代码前，运行一次 index_project(path=project_root)，并在进行非简单编辑前使用 analyze_edit_region(...)。编辑后：edit_file(base_revision=rev) -> verify(checksums)。交接前：使用 changes() 检查差异。

输入

输入	必需	来源	描述
taskId	是	args、父级 Story、看板、用户	要执行的任务

**解析：**任务解析链。 **状态筛选：**Todo

任务存储模式

**必须阅读：**加载 references/environment_state_contract.md、references/storage_mode_detection.md、references/tracker_provider_contract.md、references/provider_file.md 和 references/input_resolution_pattern.md

提取：task_provider = Task Management → Provider（linear | github | file）。此技能中的操作与提供方无关——规范操作集请参阅 references/tracker_provider_contract.md，传输绑定请参阅 provider_*.md。

工具策略：遵循宿主 AGENTS.md 中的 MCP 偏好；仅当宿主策略缺失或 MCP 行为不明确时，加载 references/mcp_tool_preferences.md 和 references/mcp_integration_patterns.md。——代码文件可用时使用 hex-line MCP；涉及语义编辑风险的问题使用 hex-graph。

模式检测

启动时检测运行模式：

计划模式已启用：

• 步骤 1-2：加载任务上下文（只读，在计划模式下可以执行）
• 生成 EXECUTION PLAN（要创建/修改的文件、实施方法）→ 写入计划文件
• 调用 ExitPlanMode → 停止。不要实施。
• 步骤 3-6：获批后 → 执行实施

正常模式：

• 步骤 1-6：按标准工作流执行，不暂停

使用 TodoWrite 跟踪进度

无论处于哪种模式，技能都必须创建详细的待办清单，跟踪所有步骤。

规则：

1. 在步骤 1 之前立即创建待办事项
2. 每个工作流步骤单独列为一项待办；实施步骤应包含子项
3. 开始步骤前将其标记为 in_progress，完成后标记为 completed

待办模板（10 项）：

Step 1: Resolve taskId
  - Resolve via args / Story context / kanban / AskUserQuestion (Todo filter)

Step 2: Load Context
  - Fetch full task description + linked guides/manuals/ADRs

Step 2b: Goal Articulation Gate
  - Complete 4 questions from references/goal_articulation_gate.md (<=25 tokens each)

Step 2c: Implementation Blueprint
  - From task "Affected Components": extract file paths (Glob/Grep or narrow `inspect_path(path=<component dir>)` to find actual paths)
  - Read each file (or key sections) to understand current structure
  - IF modifying existing code in supported languages: `index_project(path=project_root)` once, then use path-scoped `find_symbols` / `inspect_symbol` for exact symbol identity and `analyze_edit_region` before editing non-trivial ranges
  - IF `find_symbols` returns `partial ... truncated=1` or a broad candidate set: refine to `name + file` or `workspace_qualified_name` before planning from it
  - Output:
    ## Implementation Blueprint: {taskId}
    **Files to create:** [list with brief purpose]
    **Files to modify:** [list with what changes]
    **Change order (dependencies first):**
    1. {file} — {what and why first}
    2. {file} — {depends on step 1}
    **Risks:** {shared files with parallel tasks, if any}
  - Scope: ONLY files of this task. Do not analyze other tasks.

  - **Checkpoint:** Emit PHASE_3 checkpoint with structured `blueprint` payload:
    `{ "blueprint": { "change_order": [{ "file": "...", "action": "create|modify", "reason": "..." }] } }`
    Guard blocks PHASE_4 if blueprint is missing from the checkpoint.

Step 3: Start Work
  - Set task to In Progress, update kanban

Step 4: Implement
  - 4a Pattern Reuse: IF creating new file/utility, Grep src/ for existing similar patterns
    (error handlers, validators, HTTP wrappers, config loaders). Reuse if found.
  - 4b Follow task plan/AC, apply KISS/YAGNI
  - 4c Architecture Guard: IF creating service function: (1) 3+ side-effect categories in **leaf** function → split (EXCEPT orchestrator functions that delegate sequentially — these are expected to have 3+ categories);
    (2) get_*/find_*/check_* naming → verify no hidden writes; (3) 3+ service imports in **leaf** function → flatten (orchestrator imports are expected)
    (4) **Frontend Guard (conditional):** IF affected files include `.tsx/.vue/.svelte/.html/.css` → **MANDATORY READ:** Load `references/frontend_design_guide.md`. Load project's design_guidelines.md if exists (design tokens source of truth). Verify: one composition per viewport; max 2 typefaces + 1 accent color; cards only when interaction requires; motion max 2-3 purposeful; WCAG 2.1 AA contrast (4.5:1 text, 3:1 UI elements)
  - Update docs and existing tests if impacted
  - Execute verify: methods from task AC (test/command/inspect)

Step 5: Quality
  - Run typecheck and lint (or project equivalents)
  - 5b Blueprint Completion: compare actual changes to blueprint; emit blueprint_status in PHASE_6 checkpoint

Step 6: Finish
  - Set task to To Review, update kanban
  - Add summary comment (changes, tests, docs)

工作流（简要）

1. 解析 taskId： 按照指南运行任务解析链（状态筛选：[Todo]）。
2. 加载上下文： 通过已配置的任务跟踪提供方（getTask）获取完整任务说明；阅读关联的指南、手册、ADR 和研究资料；必要时自动发现团队/配置。 2b) 目标关卡： 必须阅读： 加载 references/goal_articulation_gate.md — 完成 4 个问题的关卡（每项不超过 25 个词）。说明真实目标（以交付物为主体）、完成标准、非目标、不变量和隐藏约束。 2c) 实施蓝图： 根据任务的“受影响组件”，通过 Glob/Grep 或范围受限的 inspect_path(path=<component dir>) 找到实际文件路径。阅读每个文件的关键部分。如果任务要修改受支持语言中的现有代码，则构建一次图上下文（index_project），并使用按路径范围限定的 find_symbols / inspect_symbol 确认准确的符号标识，再在编辑重要代码范围前运行 analyze_edit_region。如果符号发现结果被截断，则在规划前使用 name + file 或 workspace_qualified_name 缩小范围。输出结构化计划：要创建/修改的文件、变更顺序（依赖项优先）、风险（被并行任务共用的文件、外部调用方、公共 API 面）。
3. 开始工作： 通过已配置的任务跟踪提供方（updateStatus）将此任务更新为 In Progress；在看板中移动任务（保留 Epic/Story 缩进）。
4. 实施（含验证循环）： 编写新工具/处理程序前，在 src/ 中使用 Grep 查找现有模式（错误处理、验证、配置访问）。如有可复用模式，则复用；若不可复用，在代码注释中说明理由。修改现有函数、类、路由或中间件前，先运行 analyze_edit_region，并考虑外部调用方、同类代码、下游流程和公共 API 风险。遵循复选框/计划；保持简单；避免硬编码值；复用现有组件；更新“受影响组件”中注明的文档；如有影响则更新现有测试（此处不新增测试）。创建服务函数前，应用架构防护措施（级联深度、接口诚实性、扁平化编排；对于前端文件：必须阅读 references/frontend_design_guide.md，如果存在则加载 design_guidelines.md，并验证组合/排版/WCAG 规则）。实施后，执行任务 AC 中的 verify: 方法：test → 运行指定测试；command → 执行并检查输出；inspect → 验证文件/内容存在。如有任何验证失败 → 修复后再继续。
5. 质量： 运行类型检查和 lint（或项目对应检查）；确保已处理“现有代码影响”中的说明。蓝图完成情况： 将实际变更与第 2c 步的蓝图逐项对比——对每个计划内文件标记为已完成或已跳过（并说明理由），对每个计划外文件标记为已添加（并说明理由）。输出 PHASE_6 检查点：{ "blueprint_status": { "planned_count": N, "completed": [...], "skipped": [{"file":"...","justification":"..."}], "added": [{"file":"...","justification":"..."}], "completion_pct": N } }。如果缺少此项，防护机制将阻止 PHASE_7。
6. 收尾： 通过已配置的任务跟踪提供方（updateStatus）将任务标记为 To Review；在看板中将任务更新为 To Review；添加总结评论（变更内容、运行的测试、涉及的文档）。

提交前检查清单

背景： 在移至待审查状态前进行自我评估，可减少审查往返，并及早发现明显问题。

必须阅读： 加载 references/code_efficiency_criterion.md——提交前进行自检。

设置为待审查前，确认以下所有事项：

#	检查项	验证
0	已验证 AC	已执行每项 AC 的 verify: 方法，并提供通过证据
1	方案一致性	实现符合 Story 的技术方案
2	代码整洁	无无用代码、无向后兼容垫片、已移除未使用的导入
3	配置规范	无硬编码凭据、URL 或魔法数字
4	文档已更新	受影响组件的文档已反映所做更改
5	测试通过	更改后现有测试仍然通过
6	复用模式	已对照现有代码库检查新增工具；未引入重复模式
7	架构防护	级联深度 <= 2（叶子函数）；名称表示读取的函数中无隐藏写入；叶子函数中无 >= 3 层的服务链（编排器导入除外）。前端文件：按照 references/frontend_design_guide.md 检查组合、排版和 WCAG
8	破坏性操作安全	如果任务包含“破坏性操作安全”部分：(1) 在执行破坏性代码前已执行或规划备份步骤，(2) 代码中存在回滚机制，(3) 存在环境防护，(4) 已附上或引用预览/试运行证据
9	代码效率	无不必要的中间步骤；冗长模式已替换为语言惯用写法；无样板化的框架处理代码（参见 references/code_efficiency_criterion.md）
10	蓝图已完成	所有蓝图项目均已完成，或已跳过并说明理由；已在 PHASE_6 检查点输出 blueprint_status

必须阅读： 加载 references/destructive_operation_safety.md，了解严重性分类和安全要求。

人工确认关卡： 如果任务严重性为 CRITICAL（依据上文加载的 destructive_operation_safety.md）：使用 AskUserQuestion，在标记为待审查前确认：“任务包含 CRITICAL 级别的破坏性操作：{operation}。备份计划：{plan}。是否继续？”用户确认前，不得标记为待审查。

如果任何检查未通过： 在设置为待审查前修复。不要指望审查者发现本可预防的问题。

关键规则

• 每次只更新单个任务；不得批量更改状态。
• 编辑/评论中使用任务本身的语言（EN/RU）。
• 描述中不得包含代码片段；代码应放在代码库中，而非跟踪器描述中。
• 不得新建测试；仅在需要时更新现有测试。
• 保持编排器规定的 Foundation-First 顺序；不得调整任务顺序。
• 不得提交。 保持所有更改未提交，由审查者审查并提交。
• 对现有代码进行非琐碎编辑前，如有图谱影响证据，应使用该证据，而非仅根据文件名猜测影响范围。

运行时摘要工件

必须阅读： 加载 references/coordinator_summary_contract.md、references/worker_runtime_contract.md、references/task_worker_runtime_contract.md

共享契约：

• 输出 summary_kind=task-status
• 独立模式省略 runId 和 summaryArtifactPath
• 受管模式须在工作器写入经过验证的摘要前，传入 runId 和准确的 summaryArtifactPath

监控（2.1.98+）： 预计验证命令耗时超过 30 秒时，使用 Monitor。后备方案：Bash(run_in_background=true)。

完成定义

• 已选择任务并将其设为进行中；看板已相应更新。
• 已阅读指南/手册/ADR/研究资料；方案符合任务的技术方案。
• 已按计划/AC 完成实现；已执行每项 AC 的 verify: 方法，并提供通过证据。
• 已更新文档和受影响的测试。
• 类型检查和 lint 已通过（或已运行项目质量检查命令），并在评论中提供证据。
• 已将任务设为待审查；看板已移至待审查；已添加摘要评论。
• 已将运行时摘要工件写入共享的 task-status 位置。

Reference Files

• Environment state: references/environment_state_contract.md
• Storage mode operations: references/storage_mode_detection.md
• Guides/manuals/ADRs/research: docs/guides/, docs/manuals/, docs/adrs/, docs/research/
• Kanban format: docs/tasks/kanban_board.md

---

Version: 3.0.0 Last Updated: 2025-12-23