dsh-goalloop-agentteams
Deterministic goal-completion gate for DeepSeek Harness — ports the judging face of the goal-loop skill onto native Agent Teams + the task board, and drives the full agentic loop from one trigger.
Contract-first acceptance criteria, a gate that re-runs every check itself (zero model trust), verdicts bound to a tree digest, and a hard deny on false completion at update_goal / agent_teams_update_task / team_task_update via tools/pre-execute. The portable team-file protocol and dual-ledger bookkeeping from goal-loop are deliberately not ported — native Agent Teams is strictly stronger.
Trigger the loop: /goal-loop-at <objective> (or the goal_loop_at tool) writes the contract + round config, returns the loop protocol and suggested Agent Teams tasks derived from each AC. Iterate via goal_gate_check (score, trend, failedActions), claim completion only on GO.
中文简介
dsh-goalloop-agentteams 是面向 DeepSeek Harness 的确定性目标门控 + 目标闭环插件：
- 判命面：契约先行的 AC 文法，门控自己重跑每条 check（零模型参与），verdict 绑定文件树摘要（文件改动即作废过审结论），目标级假完成 2 次即
BLOCKED 等人——模型永远不能自我宣布完成。
- 闭环面：
/goal-loop-at <目标> 一条命令触发完整 agentic loop——写契约骨架 + 轮次预算（loop.json）+ 循环协议 + 从每条 AC 派生的 Agent Teams 建议任务；goal_gate_check 输出 score/趋势/failedActions，score 不得回退，NO-GO 的失败项直接变 repair 任务。
- 评估面：
maximize 按基线判定（baseline: delta 严格改善 / abs 不回退）、judged 以 probe 为确定性判官、metric: 正则提取指标、Goodhart 三防线（unverifiable ≠ passed / 判官缺失 / 基线未建）。
- 分级治理：
update_goal 完成声明永远硬拦；任务级声明按 exit: strict|goal-only 分级，多任务 Agent Teams 循环不会死锁。
完整中文文档见 README.zh.md。
Why / 为什么需要它
DSH already has two layers of completion judgement — but neither is a deterministic gate:
| Layer | Judges | Gap |
|---|
dsh-agent-teams quality kinds | Did each step follow its contract | verify commands are not re-executed by the runtime; commandsRun exit codes are member-supplied |
dsh-task-board acceptance gate | Does it look right semantically | LLM A/B comparison (threshold 0.65) — and every card can opt out via skipVerification |
dsh-goalloop-agentteams is the hard floor underneath both: it re-runs every AC's check command itself, binds verdicts to a tree digest, and counts caught false-completes — two catches → BLOCKED. Deterministic gate = floor, LLM judge = semantic layer, quality kinds = step contract. Stacked, they close the loop.
Contract grammar / 契约文法
objective: <one-line goal>
[exit: goal-only | strict]
AC-1 | <yes/no statement> | check: `<command>` | [probe: `<probe>`] | [metric: `<regex with one capture group>`] | [baseline: delta|abs] | expected: <spec>
AC-2 | ... | check: `...` | expected: exit=0
Spec = exit=0 | <op><number> (<=5, >0, =3) | maximize | judged.
Every check must be a named, failable command — include the environment dependency, the empty case, the error path — or the gate degrades into a tautology.
[probe:] is verify-the-verifier (R9): the probe runs first; a probe failure marks the AC unverifiable rather than passed. More than 1/3 unverifiable → the whole gate returns NO-GO.[metric:] extracts the metric value from stdout (one capture group). Without it the gate falls back to the last number in the output — write metric: whenever the output contains other numbers.maximize compares against the previous round's metric: baseline: delta requires strict improvement, baseline: abs (default) requires no regression. The first run has no baseline → unverifiable (run goal_gate_check once to establish it).judged uses the probe as a deterministic judge — the probe's exit code is the verdict. Without a probe, or when the judge command is missing (exit 127), judged is unverifiable (a broken verifier is not a failing verdict).- Contract lives at
.goal-gate/goal.md in the workspace root.
Gate & interception / 门控与拦截
goal_gate_check re-runs every check itself:
rc=0 GO / rc=2 NO-GO / rc=3 BLOCKED / rc=4 state error- Output carries the optimization signal:
score (passed/total), round / maxRounds / remainingRounds, bestScore, regression (score dropped below the high-water mark), trend (last 5 rounds), failedActions (per-AC repair list)
- Interception is mounted on
tools/pre-execute with claim scoping: update_goal(action:'complete') (the goal-level claim) is always hard-gated against the full contract with the R1 false-complete counter. Task-level claims — agent_teams_update_task(status:'completed'), team_task_update(action:'complete'), legacy update_task(status:'completed') — follow the contract's exit: policy:
exit: strict (default): full-contract hard gate + strike (single work unit: task completion is goal completion)exit: goal-only (what goal_loop_at writes): mid-loop task progress passes (step-level truth belongs to quality-kind contracts); GO binds a digest, NO-GO is recorded as partialCompletes only. Without this split, every multi-task team deadlocks: a member finishing its own task is denied because teammates' ACs are still failingBLOCKED (two caught false goal-completes) freezes every completion claim
Goal loop / 目标闭环（right loop · right eval · right metric）
/goal-loop-at <objective> (slash command) or goal_loop_at (tool) starts the loop:
- writes the contract skeleton (placeholder checks are fail-closed
TODO-REPLACE-ME) and .goal-gate/loop.json (maxRounds, default 8);
- returns the loop protocol and suggested Agent Teams tasks derived from each AC;
- every gate evaluation is appended to
.goal-gate/history.jsonl (ts/trigger/round/code/score/totals/failed ACs) — the trajectory the loop optimizes against;
- NO-GO → turn
failedActions into repair tasks, re-check; never claim completion before GO. Two caught false-completes → BLOCKED (human). The round budget counts optimization iterations only (check / completion-claim evaluations) — goal-only milestone records don't consume it; budget exhausted → roundsExhausted, stop and escalate.
Self-optimization rule: score must not regress (regression: true → fix the regression first); maximize ACs with baseline: delta require strict metric improvement round over round.
Loop driver fallback / 循环驱动兜底: a resumed session may lack the goal_gate_* tools — drive the loop from any session via bin/gate.mjs check --cwd <workspace> (absolute-path node), same ledger, same output shape. Eval hardening: preflight flags fragile check commands (bare node/python, relative interpreters, tautology suspects) and neverFailed lists ACs that have never failed (suspected tautologies).
Three hard constraints / 三条硬约束（实测所得）
From an ordering probe (tools/pre-execute waterfall semantics, real deny-return shape):
- Waterfall is first-registered-first-block. Only the earliest registered layer's deny reason reaches the user; later layers are never called. So the reason must carry its own
code ([goal-gate:no-go] / verdict-stale / blocked) — otherwise the user can't tell which layer blocked.
deny and throw are different propagation mechanisms and must not be mixed. dsh-agent-teams's quality-gate rejects by throwing, which blows through the waterfall and hands the caller an exception; the task board returns a structured {kind:'deny'}. This plugin always uses structured deny — never throw — so its error path stays distinct from quality-gate exceptions.- Digest binding must be self-built. DSH has no verdict↔file-tree binding anywhere (only state-key hashes). This plugin stores the digest and re-computes it before denying, so a passing verdict is voided automatically when the tree moves (R7).
R7 digest caveat / R7 摘要的坑（已修）
If treeDigest walks the ledger directory, writing the ledger changes the digest → the gate spuriously invalidates its own verdicts and R1's false-complete counter never reaches 2. Fixed: the digest excludes .goal-gate, node_modules, .git.
Interpreter constraint / 解释器约束
The DSH Host bundles Node 24.21.0 (runtime/primary-runtime/dependencies/node/bin/node). A node on PATH may be broken (e.g. SIGKILL on launch). Plugins run inside the Host runtime — never write a bare node in a gate script; if you must spawn a child, resolve it via config.node ?? process.execPath (the pattern dsh-skill-office uses).
Install / 安装
dsh plugin add dsh-goalloop-agentteams
Or from source: the repo declares dsh.bundle in package.json with a cordis.patch.yml beside it, so dsh plugin add picks it up directly. apply(ctx, config) registers the goal_loop_at / goal_gate_init / goal_gate_check tools, the /goal-loop-at / /goal-gate commands, and the tools/pre-execute listener.
⚠️ Entry contract (learned the hard way): the entry must export name — equal to the id in cordis.patch.yml — alongside inject and apply. A missing name makes the Host silently skip the bundle: no tools, no interception, no error anywhere. Shim-based tests cannot catch this; verify tool registration against a restarted Host.
Tests / 测试
node test/run-local.mjs
The real @deepseek-ai/dsh-tools lives inside the DSH Host and is not importable outside it, so the runner injects a minimal defineTool shim from test/fixtures/dsh-tools-shim for the duration of the run.
Mapping to goal-loop / 与 goal-loop 的对应
| goal-loop | This plugin |
|---|
| AC contract grammar + sha1 stamp | parseContract / contractStamp (R3) |
goal_gate.sh --check re-run | runGate (R9 probe + expected-spec judgement) |
| digest-bound verdicts (R7) | treeDigest + verdict-stale deny |
| R1 false-complete count → BLOCKED | falseCompleteRule |
/goal-loop-at trigger + loop orchestration | goal_loop_at tool / /goal-loop-at command + loop.json round budget |
| metric trajectory / self-optimization | history.jsonl + score / bestScore / regression |
goal_team.sh portable layer + dual ledger | dropped — use native Agent Teams + task board |
License / 许可
MIT
