Gate Customization

Gate 定制（settings.gates 完成门）

本技能教你在目标仓库的 harness.yaml 里声明任务完成门：挂本地测试、设人工签字卡点、配双控与特批、免除内置门。所有字段与行为以当前源码为准——契约在 packages/kernel/src/domain/completion-contract.ts，YAML 读写与校验在 packages/kernel/src/domain/settings.ts，逐门判定在 packages/kernel/src/domain/closeout-readiness.ts（judgeGateWitnesses），适配器执行与人工见证准入在 packages/daemon/src/repo-cell-witness-adapters.ts。改配置前先读这几个文件里你要用的部分，不凭记忆写。

模型：声明 × 映射 × 冻结

完成门是三层拼起来的，缺一层都不工作：

判定规则（fail-closed）：

• 任务声明了 gate 而 settings.gates 没有它的映射 → submit 报 gate_mapping_invalid，不是静默跳过。
• 映射到 none → 该需求被移除，不铸造虚假 pass。
• 仓库映射了一个没有任何任务声明的 gate id → 合法但惰性，不产生任何要求。
• 未知适配器、未知字段、字段集不精确 → 读设置即报错。

内置 preset 只声明两个 gate id：ci 与 code-doc-reconciliation。要用自定义 id（如 lint、signoff、merged-to.main），任务侧必须有一个声明了它的 preset：按 preset-creator 打包（profile 的 completionGates 写入自定义 id），ha preset install --source <包目录> 安装，ha task create --preset <id> 使用。只改 settings.gates 不换 preset，自定义 gate 不会被任何任务要求。

两个编译期剔除规则（在任务创建时就生效，先于任何映射）：

• settings.ci.workflows 为空数组（或缺整个 ci: 段）→ preset 解析把 ci 从任务的 completionGateIds 里剔除（packages/preset/src/preset-runtime.ts profile.completionGateIds 处）。无 GitHub CI 的仓想让测试在本地见证，用自定义 gate id 配 preset，不要指望 ci 映射。
• workKind: docs 的任务 → ci 与 code-doc-reconciliation 都被剔除（packages/preset/src/preset-bootstrap.ts withoutCodeDeliveryGates）。

settings.gates 语法

写在 harness.yaml 的 settings: 下。缩进敏感：gates: 两空格、gate id 四空格、字段六空格；字段行顺序任意；值后可跟注释。

settings:
  ci:
    workflows: [rewrite-ci]        # github-actions 适配器共用的 workflow 注册表
  gates:
    ci:                            # 块形式：下面六空格字段
      adapter: github-actions
      appliesTo: code
      branch: main
      event: push
      coverage: descendant
      selection: newest
    lint:                          # 自定义 id（需 preset 声明）
      appliesTo: code
      adapter: local-command
      command: npm ci && npm run lint
    signoff:
      appliesTo: submission
      adapter: manual-attest
    code-doc-reconciliation: none  # none 只能内联，后面不许再跟字段

解析规则（settings.ts readGateSettings/gateSettingsSchema/gateWitnessMappingIssues）：

• gate id 模式 ^[A-Za-z0-9][A-Za-z0-9/_.@-]*$：不含空格和冒号。合并门写 merged-to.main，不写 merged-to:main。
• 行内值只允许 none；ci: github-actions 这种行内写法直接报 settings.gates cannot read line。
• 每个适配器的字段集是精确的，多一个少一个都报 must declare exactly：

• mandatorySignoff / allowOverride 是治理修饰字段，不计入上面的精确集：只许写在 github-actions 与 local-command 上，写在 manual-attest 或 none 上会报 cannot declare mandatorySignoff or allowOverride（人工见证的门不再需要这两个修饰）。值必须是 YAML 布尔 true/false，其他写法（如 yes）被 schema 拒；只有 true 会进入冻结契约，写 false 等价于不写。

• github-actions 的 workflow 清单不写在 gate 映射里，统一来自 settings.ci.workflows（内联数组 [a, b]，名字不带 .yml）；映射了 github-actions 而 workflows 为空 → 解析报错。

• branch/event 值受 ^[A-Za-z0-9][A-Za-z0-9/_.@-]*$ 限制；coverage 只认 exact（run 的 head SHA 必须就是提交 SHA）或 descendant（run 的 head SHA 以提交 SHA 为祖先）；selection 只认 newest。

• 同一 gate 内字段重复、六空格字段出现在 gate 行之前、未知行 → cannot read line。

• # 在任何行内都起注释作用并被剥离——命令值里不能出现 #（command: echo a#b 会变成 echo a）。

• code-doc-reconciliation 是 Harness 内部检查器，只能映射 none，映射任何适配器都报错。

• gates 是 repository-owned 设置；ha settings update 的输入字段不含 gates，手工编辑 harness.yaml 是正式通道，重写其他设置不会动 gates 段。改完用 ha settings show 回读校验。

appliesTo 选择

枚举就三个（completion-contract.ts gateAppliesTo），按提交 cut 的形状生效：

判定语义：不适用的 gate 在该 cut 上记 not_applicable，不阻塞也不需要证据。混合交付（commit + artifact）同时承载两类 gate。

实践规则：

• local-command 需要 commit cut（它要把提交物化成沙箱）；artifact-only 交付上它会报 witness_unavailable。纯文档/产物型交付用 manual-attest。
• 仓库同时有代码任务和文档任务时，把代码门圈成 appliesTo: code，文档任务不会被卡死；交付级卡点（如 owner 签字）用 submission。

场景：local-command（本地命令见证）

把一条 shell 命令当作 gate 的见证人。执行语义（repo-cell-witness-adapters.ts collectLocalCommand）：

• 触发时点：task-submit 与 task-complete 的写队列之前自动采集；每次都重新采集，直到该 gate 已有绑定当前 cut 的 accepted pass 见证（或已被 owner 特批为 waived——waived 门不再重采）。上次的 fail 不会被冻结成终局——修好后重跑 task complete 会采到新的 pass。
• 沙箱：daemon 把精确的提交 commit用 git archive 解到全新临时目录再运行命令。命令看到的是提交时的内容，不是工作树；目录里没有 .git。临时目录用后即删，两次运行之间不保留任何状态（依赖装了什么都不会留下）。
• 命令形式：sh -c "<command> 2>&1"，stdout 与 stderr 合并。
• 环境变量：只有 PATH 加下面三个，父进程其余环境（HOME、node/npm 配置等）一概不传：

• 退出码即裁决：0 = pass；非零 = fail（complete 时以 invalid_proof 阻塞完成；门声明了 allowOverride 时 fail 先作为正式回执落库，blocker 改给特批命令）；启动失败、被信号杀死或超过 10 分钟 = witness_unavailable（证据不可得，不是 pass 也不是 fail，任务停在 gate 未满足上）。
• 防陈旧：观测绑定 commitSha + submissionDigest；提交被 amend 或契约变化后，旧观测作废、需要重采。
• 可达性：提交必须存在于本节点可读的仓库（仓库根或该任务派工的 worktree）。worker 在 worktree 里 commit 而没让 daemon 读得到，会报 witness_unavailable。
• 留痕：provenance 记 exit N; output sha256:…; tail "…"（输出摘要 + 最后约 500 字符），不存全量输出。

写命令的守则：

1. 自带依赖安装（沙箱每次都是新的）：npm ci && npm test、python3 -m venv .venv && …。
2. 不要依赖 HOME 类缓存。实测在最小环境下：Go 必须显式 export GOCACHE="$PWD/.gocache"，否则报 GOCACHE is not defined and $HOME is not defined；Rust 建议显式 export CARGO_HOME="$PWD/.cargo-home"（有依赖时注册表也走它）。
3. 需要读 git 历史的检查（合并门、tag 检查）用 git -C "$HARNESS_WITNESS_REPO"，不要指望工作目录里有 .git。
4. 超时是 10 分钟：全量安装+全量测试放不进一条命令时，拆成多个 gate 或让命令自建缓存目录。

合并门示例（决策 dec_59FA45A407F850E2B167A192D7 的 merged-to 形态，用自定义 gate id 配 preset 声明后生效）：

  gates:
    merged-to.main:
      appliesTo: code
      adapter: local-command
      command: git -C "$HARNESS_WITNESS_REPO" merge-base --is-ancestor "$HARNESS_WITNESS_CUT" refs/heads/main

行为：提交时 main 还没包含该 cut → 采到 fail（不阻塞 submit，verdict 在 complete 时判）；合并进 main 后重跑 task complete → pass。

场景：manual-attest（人工签字卡点）

适配器本身不采集任何观测：见证由人通过 CLI 写入。

ha task attest <task-id> --gate <gate-id> --result pass --note "审阅意见"

• --result 只认 pass 或 fail；--note 可选，会进证据的 rawResult；--mode 缺省为 approve。
• 前置条件（缺一即拒）：任务当前 iteration 有已提交的 execution；该 gate 在冻结契约里；该 gate 声明的适配器就是 manual-attest（给声明为 github-actions 且无 mandatorySignoff 的门 attesting 会以 invalid_command 拒绝——人工 pass 不能顶替声明的见证来源）；appliesTo 与该 cut 匹配（code 门不能在 artifact-only cut 上签字）。
• 证据 provenance 为 source: human，绑定当时的执行身份。带 executor 的 runtime 会话永远不能以人工身份签注（actor_unauthorized）——签注只认人类 principal。它不替代 Review/Consent 流程，只是 gate 见证。

适合：无自动化环境的签字卡点、artifact-only 交付的人工审阅、上线前 owner 批准。

场景：mandatorySignoff（自动见证 + 强制人工签注，双控）

在 github-actions 或 local-command 门上加 mandatorySignoff: true：

  gates:
    ci:
      adapter: github-actions
      appliesTo: code
      branch: main
      event: push
      coverage: descendant
      selection: newest
      mandatorySignoff: true

行为（judgeGateWitnesses）：自动见证 pass 后门状态是 signoff_missing 而不是 passed——complete 的 blocker 直接给出签注命令：

ha task attest <task-id> --gate ci --result pass

• 签注走同一个 task attest 入口，--mode 缺省 approve；它要求本 cut 已有被接受的自动 pass，否则拒 invalid_transition（先跑 ha task complete 让见证落库）。approve 不能带 --rationale（那是 override 的字段，invalid_field），可用 --note。
• 任何 human principal 都能签注（不限 owner）；runtime executor 不能。
• 签注与自动见证是两个独立证据槽位（lane）：人签不覆盖机器记录，机器重采也不覆盖人签。
• manual-attest 与 none 门不能声明此字段。