ns-execution-gitlab-issue

执行 GitLab Issue

对于外部 GitLab ISSUE_URL，入口优先级为 1。当 delivery-units.md 提供 unit + issue_iid（而非外部 URL）时，使用下文的 SDD 单元模式。完整路由：../../ns-harness/references/code-skill-routing.md。

路由（先阅读）

入口优先级为 1。Harness 表：../../ns-harness/references/code-skill-routing.md。触发短语：references/entry-triggers.md。

交接	目标
Phase 2 执行（外部，单个单元）	在现有工作树中使用 coder-agent → ns-coder — 跳过 ns-autonomous（单单元 planning-decision.md；生成门控）
Phase 2 执行（外部，多个单元）	ns-autonomous（Engine 模式）
Phase 2 执行（SDD 单元）	../../ns-coder/references/run-implementation.md（仅限单元任务）
MR / 状态 / 耗时 / 评论	mcp-gitlab-usage
Phase 4 审核门控	reviewer-agent → ns-reviewer；仅当 Code Review: Approved 时，在当前会话中使用 ns-judge
驳回后的修复循环（外部，单个单元）	coder-agent / ns-coder（同一工作树；不使用 A）
驳回后的修复循环（外部，多个单元）	ns-autonomous → C2（同一工作树；不得从 A / C2 重新进入此技能）
驳回后的修复循环（SDD 单元）	coder-agent → ns-coder / run-implementation（同一工作树；不使用 ns-autonomous）

交付前，G 始终是 GitLab 生命周期的唯一负责人。A 下的外部多单元流程不得重新打开此技能。外部单单元 + SDD 单元的 Phase 2 跳过 A。

会话启动

参见 ../../ns-harness/references/session-boot.md。在进行任何 MCP 调用之前，必须先完成该处的会话启动（阻塞）。会话启动后阅读 mcp-gitlab-usage。

输入

变量	必填
ISSUE_URL	外部 Issue 模式下必填
unit + issue_iid	SDD 单元模式下必填（来自 delivery-units.md）
SOURCE_BRANCH	否 — 若省略，由 Gate 1 解析

外部 Issue 模式（优先级 1 保持不变）：每个 Issue 使用一棵工作树、一个分支、一个 MR、一个提交：

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

SDD 单元模式 — 当 ns-spec-driven 分派已发布的交付单元时：

• 输入：来自 delivery-units.md 的 unit ID（例如 unit-001）+ issue_iid — 不是外部 ISSUE_URL
• WORKTREE_ROOT = .worktrees/{unit}
• WORK_BRANCH = work/{unit}-{slug}，遵循 delivery-units.md / source-branch-resolution.md
• SOURCE_BRANCH = delivery-units.md 标题中记录的版本解析分支（Gate 1 使用相同规则；若标题中已设置，则跳过重新发现）
• Phase 2 编码：仅限单元任务使用 ../../ns-coder/references/run-implementation.md — 不使用 ns-autonomous Engine
• 状态/耗时：此技能负责生命周期（First act + Phase 3）。跳过 Flow D。引用 ../ns-spec-driven/references/delivery-units.md GitLab 状态/耗时（SSoT）
• 在 Phase 3 为每个单元调用一次 add_issue_spent_time（实际耗时）— 不按任务计算，也不累加估算值

Phase 0 — 上下文（MCP 前完成启动）

1. 会话启动（阻塞） — 在进行任何 MCP 调用之前，完成 ../../ns-harness/references/session-boot.md。
2. 确保 .worktrees/ 已加入 gitignore（参见 references/worktree-setup.md）。
3. 在首次 MCP 调用前阅读 mcp-gitlab-usage。
4. 检测模式： 外部 ISSUE_URL → 外部 Issue 模式。来自 delivery-units.md 的 unit + issue_iid → SDD 单元模式 — 设置下文中的 WORKTREE_ROOT、WORK_BRANCH、ISSUE_ID 替代值。
5. 验收条件不完整（可选前置步骤）： AC 缺失、存在冲突，或过于简略而不适合自主编码 → 先运行 /ns-requirements-enricher。在 enrich 完成或人工明确跳过之前，不要开始 Phase 1（不设置 status_in_progress，不编码）。

Phase 1 — 准备

首先执行（强制，先于任何门禁）

通过 MCP 将 issue 的状态设为 status_in_progress（进行中）。如果此调用失败，立即中止并等待人工介入——对于未标记为进行中的 issue，以下步骤均不得执行。

门禁 0 — 复用现有分支/MR

某个 issue 可能已经有工作分支（例如由人工审核者提供）。请在门禁 1 之前检测，以免创建重复的分支/MR：

外部 issue 模式：

1. list_issue_merge_requests — 查找 source_branch 匹配 work/{ISSUE_ID}-* 的开放 MR；记录其 source_branch 和 target_branch。
2. 执行 git ls-remote --heads origin "work/{ISSUE_ID}-*"，作为第二个信号。

SDD 单元模式：

1. list_issue_merge_requests — 查找 source_branch 匹配 work/{unit}-* 的开放 MR。
2. 执行 git ls-remote --heads origin "work/{unit}-*"。
3. 如果 delivery-units.md 中的行包含 mr_url，则优先复用。

两种模式（复用决策）：

4. 已找到 → REUSE_MODE = true，WORK_BRANCH = {existing branch}，SOURCE_BRANCH = {existing MR target}。跳过下文的 WORK_BRANCH 推导步骤和门禁 1（只需重新验证该分支仍存在于远程）。
5. 未找到 → REUSE_MODE = false，继续执行门禁 1。

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

SDD 单元模式： 如果 delivery-units.md 标头已记录 SOURCE_BRANCH，则使用该值——除非人工覆盖本次运行，否则不要重新执行发现流程。

外部 issue 模式： 仅通过 references/source-branch-resolution.md 解析（优先级顺序：人工 → issue 文本 → 产品规则 → 里程碑/版本发现 → 必须回退到 develop）。

• 绝不要根据当前检出状态或临时启发式规则进行推断。
• 绝不要自动使用已发现的相对版本的 develop_* / develop-* 分支或 develop 回退分支之外的任何分支——其他基础分支（homolog、release/*、main、master 等）都需要本次运行中获得明确的人工确认。
• main / master 仅在本次运行中获得人工明确授权时才能作为 SOURCE_BRANCH——绝不可自动使用；issue 文本仅提及这些分支并不足以授权（请询问一次）。

解析完成后，根据同一份参考文档，在远程验证该分支（fetch、ls-remote、_ ↔ - 变体）。如果远程缺少强制要求的 develop 回退分支 → 使用准确的错误信息中止；询问操作员一次。

门禁 1.5 — 单一 worktree（monorepo）

根据 references/worktree-setup.md 创建 WORKTREE_ROOT：

• 外部 issue 模式： .worktrees/{ISSUE_ID}
• SDD 单元模式： .worktrees/{unit}

绝不要在 .cursor/ 下创建。如果该 id 已有 worktree，且正在由另一次运行使用，则中止；明确要求恢复运行时除外。绝不要在主检出目录或 main / master / SOURCE_BRANCH 上实施更改。如果 git worktree add 失败 → 使用准确的错误信息中止（不得回退到主检出目录）。隔离是进入阶段 2 前的硬性门禁。

MCP 设置

• 如果 due_date 为空：设为当前日期 + 5 个工作日。
• 此处不要设置 START_TIME——耗时计时从阶段 2 开始（参见 references/time-tracking.md）。

阶段 2 — 执行（委派）

外部 Issue 模式

1. 通过 MCP 读取完整的 Issue 载荷（标题、描述、评论、附件）。注意下文估算门槛所需的 time_stats.time_estimate。
2. 设置 START_TIME / START_EPOCH 现在（UTC 时间 + Unix 纪元）——就在首次调用编码工具之前。参见 references/time-tracking.md。
3. 规划深度门槛——在调用 A 之前，根据 Issue 载荷应用 ../ns-autonomous/references/planning-decision.md 中的启发式规则：
   • 单一单元（≤5 个文件 / 一段式验收标准，没有实际的 DAG）：跳过 ns-autonomous。必须在 WORKTREE_ROOT / WORK_BRANCH 中派发 coder-agent（若可用；否则派发 ns-coder）。派发时仅执行实现；将审查推迟到阶段 4（每次闭环审查一次，参见 ../../ns-harness/references/subagent-dispatch.md）。
   • 多单元（Requirements+tasks 路径）：调用 ns-autonomous Engine 模式，传入 Issue 载荷、WORKTREE_ROOT、WORK_BRANCH、SOURCE_BRANCH。Engine 会规划深度、处理疑问协议、派发单元——参见 ns-autonomous 的 references/routing.md。
4. **估算（仅首次调用）：**仅当 time_stats.time_estimate 为空（0 / 缺失），且工作者 / Engine 返回的 estimate_seconds ≥ 60 时，才调用 set_issue_estimate。估算已存在或数值 < 60 时——跳过；绝不覆盖，绝不写入 1 秒估算。完整规则见 references/time-tracking.md。
5. 疑问升级约定——Engine 不会修改 GitLab 状态。Engine 返回破坏性疑问事件时（仅多单元路径）：
   • 记录 PAUSE_START 纪元时间（等待期间不计入已用时间）。
   • 应用 status_blocked（Em Impedimento）。
   • 发布评论，提及 Issue 作者（从 read_issue 获取 @{author.username}），并列出问题、选项和建议的默认方案。
   • 在交互式聊天中重复同一问题并等待。
   • 收到回复后（聊天和 / 或 Issue 评论）：将暂停时长加到 PAUSED_SECONDS，将状态设回 status_in_progress（Em andamento），并附上已解决的疑问重新调用 Engine。
6. 除此循环外，不作中途确认——此循环仅在阶段 4 审查门槛前暂停。

SDD 单元模式

1. 对 issue_iid 调用 read_issue——描述中包含执行和审查清单。
2. 在单元内首个任务开始前设置 START_TIME / START_EPOCH。
3. 在 WORKTREE_ROOT 中，按 ../../ns-coder/references/run-implementation.md 执行，范围限定为单元任务——交接行按每个任务保留；此处不要运行 Flow D（状态 / 已用时间由 G 管理）。
4. 跳过 ns-autonomous Engine。跳过按任务调用 add_issue_spent_time。
5. 发布时的估算 = 任务估算之和（delivery-units.md 中的 estimate_sum）——不要按任务重新估算。

阶段 3 — 交付

1. 推送前压缩为一个 Conventional Commit（<type>(#{issue_iid}): <imperative description in English>；类型：feat/fix/refactor/test/docs/chore）。外部模式可在消息中使用 ISSUE_ID 作为 Issue 标识符。压缩内部检查点提交，以确保每次交付保持一个提交的原子性。署名参见 ../../ns-harness/references/agent-git-identity.md。
2. 推送 WORK_BRANCH。
3. 运行阶段 4（审查门槛）。在阶段 4 同时返回 Code Review: Approved 和 Delivery Review: Approved 之前，不要设置 END_TIME、已用时间或 Dev 100%。
4. 仅当结果为 Approved 时——同时停止计时并更新看板：
   • 现在设置 END_TIME / END_EPOCH。
   • 使用 references/time-tracking.md 中的 ELAPSED_SECONDS 计算 duration，调用 add_issue_spent_time（纪元时间差减去 PAUSED_SECONDS）。绝不可使用 estimate_seconds 或任何计划估算作为 duration。此技能运行完整生命周期时，已用时间仅由一个主体登记——在 delivery-units.md 行中将 spent_posted 设为 yes；Flow D 不得重复登记。
   • 状态 → status_done（Dev 100%）。
   • 使用 references/delivery-report.template.md 发布内部交付评论（internal: true）。

阶段 4 — 审核关卡（阻塞式、有界修复循环）

规范规则：../ns-reviewer/references/review-gate-workflow.md。

1. 必须在可用时调用 reviewer-agent（否则调用 ns-reviewer），并使用 Issue review mode — 传入 ISSUE_URL 或 project_id + issue_iid（SDD 单元模式）。桥接/技能会加载 AGENTS.md，然后加载审核工作流。只读 代码关卡；发布内部 GitLab 评论。不会解析 AC 或 requirements.md。**禁止：**任务子 Agent（senior-tech-lead-reviewer、bugbot、security-review）或替代工具，除非人工明确要求本次运行使用它们。允许：工具链 reviewer-agent。参见 ../../ns-harness/references/subagent-dispatch.md。审核者不得调度 judge。
2. 代码循环 = review-gate-workflow.md Code 有序契约（最多 3 次；Approved = 10）。每个映射只对应一个 coder 目标 — 绝不拆分：
   • 第 1 次 / 第 2 次调用返回 Rejected 且仍有剩余轮次 → 将映射原样传给 外部单元任务：coder-agent / ns-coder（同一工作树）；外部多单元任务：ns-autonomous（同一工作树），作为一个修复单元（不拆分映射）；SDD 单元：coder-agent / run-implementation（同一工作树）。下一条审核者提示词 = delta + 之前的映射 ID，通过 reviewer-agent（可用时必须使用；否则用 ns-reviewer）。保留 START_TIME；此时不要记录已用时，也不要设为 Dev 100%。不要调用 judge。
   • 仅在第二个 coder 完成后才进行第 3 次调用（delta 发现了残留问题和/或引入了 Critical 时）。第 3 次调用未得分 10、或结果为 Blocked、或轮次耗尽 → status_blocked（Em Impedimento），发布问题发现，然后停止。Blocked 时不要调用 coder。不要设置 END_TIME，不要记录已用时，也不要设为 Dev 100%。不要调用 judge。
3. 仅当 Code Review: Approved 时：在当前会话中读取 ../ns-judge/SKILL.md（从综合阶段传入 --mode issue --ac-file）。Python 可选。只有得分为 10 才能获得 Delivery Review: Approved。Judge 返回 Rejected：修复映射；若产品文件有更改 → 再次进行代码审核（必须为 Approved），然后再次进行 judge 审核。Judge 最多进行 3 轮。
4. 两项均为 Approved → 阶段 3 第 4 步（设置 END + 记录已用时 + Dev 100% + 发布交付评论）。
5. 最终输出：Fatto! + MR_URLS + Code Review: {verdict} + Delivery Review: {verdict} — 返回的字符串必须完全一致。

停止并询问人工

条件	操作
关卡 1：远程缺少 develop 回退分支	停止 — 询问一次
关卡 1：基础分支非默认值（main/master/homolog/…），且本次运行未获人工明确确认	停止 — 询问一次
工作树冲突（同一 issue，另一次运行正在进行）	停止，除非明确要求恢复
验收标准含糊或冲突	先停止 — 使用 /ns-requirements-enricher；不要开始阶段 1 的编码
MCP 不可用或认证失败	停止 — 说明阻塞原因
未确认 project_id 三元组	按 mcp-gitlab-usage 停止
根据 gitlab-sync-config.md 在受保护分支/基础分支上工作	停止
破坏性操作（删除 issue、对 main/master 强制推送）	停止 — 必须获得人工明确确认
issue 中未说明产品决策	停止 — 询问一次
引擎报告存在破坏性操作疑虑	按阶段 2 第 4 步暂停/恢复 — 并非硬性停止

MCP 工具契约和确认关卡参见 mcp-gitlab-usage。

相关技能

技能	作用
/ns-requirements-enricher	AC 不完整时的可选前置步骤 — 在阶段 1 之前
mcp-gitlab-usage	所有 GitLab 工具
ns-gitlab-board-sync	状态标签语义
ns-reviewer	阶段 4 代码审核关卡（有 reviewer-agent 时必须使用）
ns-judge	Code Review: Approved 后，在会话中提供阶段 4 交付证明
ns-autonomous	仅限多单元场景的阶段 2 Engine
ns-coder	外部单单元 + SDD 单元编码；非 GitLab 临时任务

参考资料

文件	使用时机
references/source-branch-resolution.md	关卡 1 — 里程碑/版本发现、develop 回退、远程验证
references/worktree-setup.md	ISSUE_ID → run_id 覆盖（规范机制见 ns-harness）
references/mr-conventions.md	MR 标题、草稿、关联、复用说明
references/delivery-report.template.md	阶段 3 内部交付评论
references/time-tracking.md	仅在为空时填写预估；按墙上时钟记录耗时 + 暂停规则