---
name: workflow-harness
description: 运行齐衡 QIHENG 候选版本约束的设计、开发、测试、质询、证据和准入门禁图。用于启动交付执行框架、冻结候选版本、记录门禁结论与证据、检查依赖完成情况、发现候选版本或项目画像漂移，以及判断整体交付是否就绪。
metadata:
  version: 1.1.17
---

# 交付保障执行框架

> **领导速读：** 冻结候选版本并运行门禁依赖图，确保每项结论有证据、可失效、可恢复。

## 一、管理视角

- **何时使用：** 项目画像就绪后启动或继续齐衡交付流程时。
- **主要输入：** 项目画像、候选版本、门禁计划、角色交接和证据。
- **主要输出：** 可执行计划、运行状态、就绪度、阻断项和管理报告。
- **职责边界：** 不允许聊天摘要替代门禁记录。

## 二、执行方法

以命令行工具作为唯一控制平面，不要另行维护人工检查清单。

### 初始化

生成 `reports/project-profile.json` 后，冻结当前 Git 候选版本：

```text
qiheng harness-init --root .
```

读取 `reports/harness-plan.json`。其中包含门禁图、候选版本哈希、依赖关系、失效范围、证据要求和项目画像驱动的执行建议。建议为 `ASSESS` 时必须明确判断是否适用，不能直接视为跳过。

### 执行

针对每一道依赖已经满足的门禁：

1. 消费上游成功门禁产生的真实产物。
2. 由主责子智能体执行门禁指定技能，并消费协作子智能体的标准交接。
3. 在项目内保存持久化证据文件。
4. 记录门禁结果：

```text
qiheng harness-record --root . \
  --gate <gate-id> \
  --status PASS \
  --summary "<范围明确的结论>" \
  --evidence <项目相对路径> \
  --handoff reports/handoffs/<agent>.json
```

`harness-plan.json` 的 `agent` 表示门禁主责，`contributors` 表示协作角色，
`requiredHandoffs` 表示通过门禁前必须消费的 `dic.agent-handoff.v1` 交接。
仅在问题不阻断且有负责人、有完成条件时使用 `PASS_WITH_FOLLOW_UP`。只有条件门禁可以使用 `SKIPPED`，并且必须说明不适用原因。必跑门禁不能跳过。`PASS` 至少需要一个真实证据文件和全部必需交接。

### 失效处理

候选版本身份包含 Git HEAD、完整已跟踪差异和未跟踪源码文件哈希；证据目录不计入候选版本字节。源码候选版本或项目画像发生任何变化，都会拒绝继续记录，并使当前运行结果失败关闭。

完成影响分析后，重新冻结新计划：

```text
qiheng harness-init --root . --force
```

不要为了清除阻断项而滥用 `--force`。需要审计历史时，应在重建前保存旧计划、运行记录和证据。

### 准入前检查与最终检查

仓库准入前先运行：

```text
qiheng harness-check --root . --for-admission --json
```

只有返回 `READY_FOR_ADMISSION`，`repository-gatekeeper` 才能执行
`admission.repository`。记录准入决定后再运行：

```text
qiheng harness-check --root . --json
qiheng harness-report --root .
```

检查会拒绝：

- 候选版本或项目画像漂移；
- 门禁缺失、失败、受阻、运行中或过期；
- 必跑门禁被跳过；
- 依赖未完成或完成顺序错误；
- 成功门禁没有证据；
- 成功门禁缺少必需的子智能体交接，或交接状态未成功关闭；
- 证据缺失、内容变化或位于项目目录之外。

`deliveryStatus: READY_FOR_ADMISSION` 表示除仓库准入外均已闭合；
`deliveryStatus: READY` 表示仓库准入也已记录且执行框架完整闭合。

将 `reports/harness-report.md` 作为高层交付保障驾驶舱。它从同一份机器状态生成候选版本身份凭证、保障范围、设计交付数字主线、门禁决策矩阵和阻断项，禁止手工修改。