LUAgam/skills/stage-gate

SKILL: stage-gate

CLI Bootstrap

在执行任何 harnessctl 命令前，校验环境变量 HARNESSCTL 是否已配置：

test -n "${HARNESSCTL:-}" && test -x "$HARNESSCTL" || {
  echo "ERROR: HARNESSCTL 环境变量未设置或不可执行。请先执行: export HARNESSCTL=/path/to/stage-harness/scripts/harnessctl" >&2
  exit 1
}

阶段门禁技能。在每个阶段出口执行产物完整性检查，确保进入下一阶段所需的所有产物齐备、决策已处理、议会已通过。

---

触发条件

• 每次调用 $HARNESSCTL state transition 前自动检查
• 收到 /stage-harness:gate 命令时手动触发
• 由各阶段 SKILL 的出口条件检查调用

---

阶段产物清单

CLARIFY 出口

| 产物 | 路径 | 说明 | |------|------|------| | domain-frame.json | .harness/features/<epic-id>/domain-frame.json | domain-scout 领域框架草稿 | | generated-scenarios.json | .harness/features/<epic-id>/generated-scenarios.json | scenario-expander 场景展开 | | scenario-coverage.json | .harness/features/<epic-id>/scenario-coverage.json | Lead 语义归并后的场景覆盖台账 | | challenge-report.md | .harness/features/<epic-id>/challenge-report.md | challenger 报告（须含 ## Summary） | | clarification-notes.md | .harness/features/<epic-id>/clarification-notes.md | 需求澄清记录（须含 Domain Frame / 领域框架 标题） | | impact-scan.md | .harness/features/<epic-id>/impact-scan.md | 影响面扫描结果（须含 ## Blast Radius Summary / ## High Impact Surfaces / ## Medium Impact Surfaces） | | surface-routing.json | .harness/features/<epic-id>/surface-routing.json | 承载面路由与扫描预算（必备；surfaces 非空且含 type/path） | | unknowns-ledger.json | .harness/features/<epic-id>/unknowns-ledger.json | 未知问题台账 | | decision-packet.json | .harness/features/<epic-id>/decision-packet.json | 决策包 | | decision-bundle.json | .harness/features/<epic-id>/decision-bundle.json | 全量决策分类 |

workspace_mode: multi-repo 时另须 cross-repo-impact-index.json（有效 JSON，repos 为数组）——由 harnessctl stage-gate check CLARIFY 校验，见 scripts/harnessctl.py。

SPEC 出口

| 产物 | 路径 | 说明 | |------|------|------| | specs/{epic-id}.md | .harness/specs/<epic-id>.md | 规格文档 | | spec-council-notes.md | .harness/features/<epic-id>/spec-council-notes.md | 轻议会审查记录（harnessctl stage-gate check SPEC 必备，与 STAGE_GATE_ARTIFACTS["SPEC"] 一致） | | verdict-light_council.json | .harness/features/<epic-id>/councils/verdict-light_council.json | 轻议会聚合裁决（建议由 harnessctl council aggregate 写入；非 CLI 门禁必备文件） |

PLAN 出口

| 产物 | 路径 | 说明 | |------|------|------| | tasks/*.json | .harness/tasks/<epic-id>.*.json | 所有 task 文件 | | bridge-spec.md | .harness/features/<epic-id>/bridge-spec.md | Bridge 产出 | | coverage-matrix.json | .harness/features/<epic-id>/coverage-matrix.json | 覆盖矩阵 | | surface-routing.json | .harness/features/<epic-id>/surface-routing.json | 与 CLARIFY 一致，PLAN 门禁复验 | | verdict-plan_council.json | .harness/features/<epic-id>/councils/verdict-plan_council.json | 计划议会 verdict |

EXECUTE 出口

| 产物 | 路径 | 说明 | |------|------|------| | receipts/*.json | .harness/features/<epic-id>/receipts/<task-id>.json | 每个 task 的 runtime receipt | | git commits | git log 中包含所有 task commit | 原子提交记录 |

VERIFY 出口

| 产物 | 路径 | 说明 | |------|------|------| | verification.json | .harness/features/<epic-id>/verification.json | 验收结果（harnessctl stage-gate check VERIFY 必备；建议含 code_review / logic_review / test_review / security / spec_compliance） | | verdict-acceptance_council.json | .harness/features/<epic-id>/councils/verdict-acceptance_council.json | 验收议会聚合裁决（当 verification.json 中无 acceptance_council / council_verdict 为 PASS 或 CONDITIONAL_PASS 时，门禁用此文件兜底；否则可不作为阻断条件） |

stage-gate check VERIFY：verification.json 须存在；其中 acceptance_council 或 council_verdict 须为 PASS/CONDITIONAL_PASS，否则尝试读取 verdict-acceptance_council.json 的 verdict 是否为 PASS/CONDITIONAL_PASS。若 verification.json 中 code_review / logic_review / test_review / security / spec_compliance 存在且值为 FAIL（大小写不敏感），或 critical_issues 非空，门禁失败。

DONE 出口

| 产物 | 路径 | 说明 | |------|------|------| | release-notes.md | .harness/features/<epic-id>/release-notes.md | 发布说明 | | delivery-summary.md | .harness/features/<epic-id>/delivery-summary.md | 交付总结 | | verdict-release_council.json | .harness/features/<epic-id>/councils/verdict-release_council.json | 发布议会裁决（必备；verdict 须为 RELEASE_READY 或 RELEASE_WITH_CONDITIONS） |

---

门禁检查流程

Step 1 — 读取当前阶段

CURRENT_STAGE=$($HARNESSCTL state get <epic-id> --json | jq -r '.current_stage')

Step 2 — 检查产物完整性

对当前阶段的每个必备产物执行存在性检查：

# 示例：PLAN 出口检查
missing=()

# 检查 tasks
task_count=$(ls .harness/tasks/<epic-id>.*.json 2>/dev/null | wc -l)
if [[ "$task_count" -eq 0 ]]; then
  missing+=("tasks/*.json (no tasks created)")
fi

# 检查 coverage-matrix
if [[ ! -f ".harness/features/<epic-id>/coverage-matrix.json" ]]; then
  missing+=("coverage-matrix.json")
fi

# 检查 council verdict
if [[ ! -f ".harness/features/<epic-id>/councils/verdict-plan_council.json" ]]; then
  missing+=("verdict-plan_council.json")
else
  verdict=$(jq -r '.verdict' .harness/features/<epic-id>/councils/verdict-plan_council.json)
  if [[ "$verdict" == "BLOCK" || "$verdict" == "FAIL" ]]; then
    missing+=("verdict-plan_council.json: verdict=$verdict (must not be BLOCK/FAIL)")
  fi
fi

Step 3 — 检查 Decision Bundle

# 检查是否有未处理的 must_confirm 项
must_confirm_count=$(jq '[.decisions[] | select(.must_confirm == true and .resolved == false)] | length' \
  .harness/features/<epic-id>/decision-packet.json 2>/dev/null || echo 0)

if [[ "$must_confirm_count" -gt 0 ]]; then
  missing+=("decision-packet.json: $must_confirm_count must_confirm items unresolved")
fi

Step 4 — 检查议会 verdict

council_verdict=$(jq -r '.verdict' .harness/features/<epic-id>/councils/verdict-plan_council.json 2>/dev/null || echo "MISSING")

case "$council_verdict" in
  BLOCK|FAIL|NOT_READY)
    missing+=("plan council verdict: $council_verdict (blocking)")
    ;;
  MISSING)
    missing+=("verdict-plan_council.json (file not found)")
    ;;
esac

Step 5 — 裁决

产物不齐全 → 阻断：

GATE BLOCKED: <current-stage> → <next-stage>

Missing artifacts:
  - <artifact-1>
  - <artifact-2>

Action required: Complete the above before advancing.

全部满足 → 自动放行：

echo "GATE PASSED: <current-stage> → <next-stage>"
$HARNESSCTL state transition <epic-id> <next-stage>

---

门禁规则摘要

| 规则 | 阻断条件 | |------|---------| | 产物完整性 | 任意必备产物缺失（以 $HARNESSCTL stage-gate check 与 STAGE_GATE_ARTIFACTS 为准） | | Decision Bundle | 任意 must_confirm 未处理 | | 议会 verdict（PLAN 等） | 对应 verdict-*.json 为 BLOCK / FAIL / NOT_READY 等阻断值 | | EXECUTE 出口 | 任意 task 缺少 receipt（或非 done/blocked） | | VERIFY 出口 | verification.json 验收字段未通过、维度 FAIL、critical_issues 非空；或兜底议会裁决不通过 | | DONE 出口 | verdict-release_council.json 缺失或 verdict 非放行值 |

---

手动强制跳过（紧急情况）

# 需要人工明确授权，记录到 decision-packet
$HARNESSCTL gate skip <STAGE> --epic-id <epic-id> \
  --justification "emergency production fix"

跳过记录写入 .harness/features/<epic-id>/gate-skips.json，供审计使用。