execute-gitlab-issue

执行 GitLab Issue

端到端管理 GitLab issue 状态——状态、分支/工作树生命周期、MR、评论、交付、评审门禁。将实际编码工作委托给 code-autonomous 引擎（Phase 2）。

Harness 发现

参阅 ../nextstage-harness/references/harness-discovery.md。调用 MCP 前先阅读 mcp-gitlab-usage。

输入

变量	必填
ISSUE_URL	是
SOURCE_BRANCH	否 — 如未提供，由 Gate 1 解析
{product_root}	工作区中有多个产品时需要

每个 issue 使用单一工作树、单一分支、单一 MR、单一提交（monorepo 模式——不按仓库循环）：

• WORKTREE_ROOT = {product_root}/.worktrees/{ISSUE_ID}
• WORK_BRANCH = work/{ISSUE_ID}-{ISSUE_SLUG}

Phase 0 — 上下文

1. 解析 {product_root}（factory：apps/{slug}/；独立仓库：仓库根目录）。
2. 加载产品上下文：遵循 ../nextstage-harness/references/artifact-layout.md 中的 Implementation boot rule。
3. 确保 .worktrees/ 已加入 gitignore（参见 references/worktree-setup.md）。

Phase 1 — 准备

首要操作（强制，在任何门禁前执行）

通过 MCP 将 issue 的状态设为 status_in_progress（进行中）。如果此调用失败，立即中止并等待人工介入——下文的任何操作都不得在未标记为进行中的 issue 上运行。

Gate 0 — 复用现有分支/MR

Issue 可能已经有工作分支（例如由人工评审者退回）。在 Gate 1 之前检测，避免创建重复分支/MR：

1. list_issue_merge_requests — 查找 source_branch 匹配 work/{ISSUE_ID}-* 的开放 MR；记录其 source_branch 和 target_branch。
2. 执行 git ls-remote --heads origin "work/{ISSUE_ID}-*"，作为第二项信号。
3. 找到 → REUSE_MODE = true，WORK_BRANCH = {existing branch}，SOURCE_BRANCH = {existing MR target}。跳过下文的 WORK_BRANCH 推导步骤，并跳过 Gate 1（只需重新验证该分支仍存在于远程端）。
4. 未找到 → REUSE_MODE = false，继续执行 Gate 1。

Gate 1 — SOURCE_BRANCH（强制、阻塞；REUSE_MODE = true 时跳过）

只能通过 references/source-branch-resolution.md 解析 SOURCE_BRANCH（优先级：人工 → issue 文本 → 产品规则 → 里程碑/版本发现 → 强制回退到 develop）。

• 绝不根据当前检出分支或临时启发式规则推断。
• 绝不自动使用除已发现的、相对于版本的 develop_* / develop-* 或回退分支 develop 以外的分支——其他基准分支（homolog、release/* 等）必须在本次运行中获得人工明确确认。
• main / master 始终不能作为 SOURCE_BRANCH，即使 issue 中提及也不例外。

解析后，按照同一参考文档的要求在远程端验证（fetch、ls-remote、_ ↔ - 替代形式）。如果远程端缺少强制回退分支 develop，则使用准确错误信息中止；只向操作员询问一次。

Gate 1.5 — 单一工作树（monorepo）

按照 references/worktree-setup.md 创建 WORKTREE_ROOT——始终为 {product_root}/.worktrees/{ISSUE_ID}，绝不放在 .cursor/ 下。如果此 ISSUE_ID 已有工作树且正由另一次运行使用，则中止，除非这是明确的恢复运行。绝不在主检出目录或 main/master/SOURCE_BRANCH 上实现。如果 git worktree add 失败，则使用准确错误信息中止（不得为了“继续进行”而回退到主检出目录）。进入 Phase 2 前必须通过隔离门禁。

MCP 设置

• 如果 due_date 为空：设为当前日期 + 5 个工作日。
• START_TIME = ISO 8601 UTC 时间戳。
• code-autonomous 引擎返回基于计划的预估值后，再调用一次 set_issue_estimate（Phase 2，第 2 步）。

第 2 阶段 — 执行（委派）

1. 通过 MCP 读取完整的问题单内容（标题、描述、评论、附件）。
2. 以 Engine 模式调用 code-autonomous 技能，并传入：问题单内容、{product_root}、WORKTREE_ROOT、WORK_BRANCH、SOURCE_BRANCH。引擎会自行决定规划深度、执行疑问处理协议，并在 WORKTREE_ROOT 中调度实现工作（单 Agent 或多 Agent）——关于“Engine 模式”的含义及其返回内容，请参阅 code-autonomous 的 references/routing.md。
3. 在首次调用引擎后，使用引擎返回的预估值调用 set_issue_estimate。
4. 疑问升级处理约定 — 引擎不会自行修改 GitLab 状态。当它返回破坏性操作疑问事件（而非单元结果，或在返回单元结果的同时返回该事件）时：
   • 应用 status_blocked（Em Impedimento）。
   • 发布一条评论，提及问题单作者（使用 read_issue 中的 @{author.username}），并列出问题、选项和建议的默认选项。
   • 在交互式聊天中复述同一问题并等待回复。
   • 收到回复（来自聊天和/或问题单评论）后：记录回复，将状态设回 status_in_progress（Em andamento），并在上下文中附上已解决的疑问，重新调用引擎。
5. 除此之外，不进行中间确认——在第 4 阶段的审核关卡之前，只有此循环会暂停流程。

第 3 阶段 — 交付

1. 推送前，将提交压缩为一个 Conventional Commit（<type>(#{ISSUE_ID}): <imperative description in English>，类型：feat/fix/refactor/test/docs/chore）。第 2 阶段中，引擎可能会在工作树中为各个工作单元留下内部检查点提交——在此处将其压缩，以确保每次交付都是一个原子提交。归属信息请参阅 ../nextstage-harness/references/agent-git-identity.md。
2. 推送 WORK_BRANCH。
3. 调用 add_issue_spent_time（ELAPSED_SECONDS = max(1, ceil(END_TIME - START_TIME))）。
4. 只有第 4 阶段返回 Approved 后，才能将状态设为 status_done（Dev 100%）——绝不可提前设置。
5. 使用 references/delivery-report.template.md 发布内部交付评论（internal: true）。

第 4 阶段 — 审核关卡（阻塞式，有限修复循环）

1. 以 问题单审核模式（ISSUE_URL）调用 code-reviewer——只读，作为正式审核关卡，并发布 GitLab 内部评论。
2. 最多循环 3 轮：
   • Approved → 继续完成第 3 阶段的状态和评论收尾（Dev 100%）。
   • 仍有剩余轮次且结果为 Rejected → 使用审核结果作为修复工作单元，在同一工作树/分支中重新调用 code-autonomous，然后重新审核。
   • 结果为 Blocked 或轮次用尽 → 将状态设为 status_blocked（Em Impedimento），发布审核结果并停止。不得达到 Dev 100%。
3. 最终输出：Fatto! + MR_URLS + Code Review: {verdict}——必须与 code-reviewer 返回的 verdict 字符串完全一致。

停止并询问人工

条件	操作
门槛 1：远程缺少 develop 回退分支	停止 — 询问一次
门槛 1：未经人工确认的非允许基础分支	停止 — 询问一次
工作树冲突（同一议题，另一次运行）	停止，除非明确要求恢复
验收标准存在歧义或冲突	停止 — 询问一次
MCP 不可用或身份验证失败	停止 — 说明阻碍
未确认 project_id 三元组	按 mcp-gitlab-usage 的要求停止
根据 gitlab-sync-config.md，需在受保护分支/基础分支上工作	停止
破坏性操作（删除议题、对 main/master 强制推送）	停止 — 需要人工明确批准
议题中未说明产品决策	停止 — 询问一次
引擎报告存在破坏性疑虑	按阶段 2 步骤 4 暂停/恢复 — 不属于硬性停止

参阅 mcp-gitlab-usage，了解 MCP 工具约定和确认门槛。

相关技能

技能	职责
mcp-gitlab-usage	所有 GitLab 工具
gitlab-board-sync	状态标签语义
code-reviewer	阶段 4 门槛
code-autonomous	阶段 2 执行引擎
code-coder	非 GitLab 临时实现

参考资料

文件	适用场景
references/source-branch-resolution.md	门槛 1 — 里程碑/版本发现、develop 回退、远程验证
references/worktree-setup.md	ISSUE_ID → run_id 覆盖（规范机制见 nextstage-harness）
references/mr-conventions.md	MR 标题、草稿、关联、复用说明
references/delivery-report.template.md	阶段 3 内部交付评论