dw-kit 1.9.3 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/rules/dw.md +14 -3
- package/.claude/skills/dw-flow/SKILL.md +35 -2
- package/.claude/skills/dw-goal/SKILL.md +22 -1
- package/.dw/config/config.schema.json +24 -0
- package/.dw/config/dw.config.yml +14 -0
- package/.dw/core/HARNESS.md +157 -0
- package/.dw/core/schemas/events/gate_auto_approved.schema.json +36 -0
- package/.dw/core/schemas/events/hard_stop.schema.json +35 -0
- package/.dw/core/schemas/events/index.json +28 -2
- package/.dw/core/schemas/events/overnight_wrapup.schema.json +29 -0
- package/.dw/core/schemas/events/parked.schema.json +39 -0
- package/.dw/core/schemas/events/subtask_completed.schema.json +35 -0
- package/.dw/core/schemas/overnight-digest.schema.json +113 -0
- package/.dw/core/templates/autopilot-cron.sh +28 -0
- package/README.md +3 -1
- package/package.json +1 -1
- package/src/cli.mjs +63 -0
- package/src/commands/autopilot.mjs +65 -0
- package/src/commands/doctor.mjs +17 -1
- package/src/commands/overnight.mjs +35 -0
- package/src/commands/trust.mjs +79 -0
- package/src/lib/autopilot-contract.mjs +97 -0
- package/src/lib/config.mjs +56 -0
- package/src/lib/event-schema.mjs +28 -0
- package/src/lib/goal-events.mjs +4 -1
- package/src/lib/overnight-digest.mjs +241 -0
- package/src/lib/tls-helpers.mjs +28 -6
- package/src/lib/trust.mjs +139 -0
- package/README.vi.md +0 -230
package/.claude/rules/dw.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# dw Workflow (consolidated)
|
|
2
2
|
|
|
3
3
|
Config: `.dw/config/dw.config.yml`
|
|
4
|
-
Full methodology: `.dw/core/` (WORKFLOW · THINKING · QUALITY · ROLES · PILLARS)
|
|
4
|
+
Full methodology: `.dw/core/` (WORKFLOW · THINKING · QUALITY · ROLES · HARNESS · AGENTS · PILLARS)
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -37,6 +37,17 @@ Default when unsure: `standard`.
|
|
|
37
37
|
|
|
38
38
|
---
|
|
39
39
|
|
|
40
|
+
## Trust Mode & Overnight Autopilot (ADR-0022/0023)
|
|
41
|
+
|
|
42
|
+
**Off by default** — every `dw:flow` gate is manual unless opted in.
|
|
43
|
+
|
|
44
|
+
- **Trust Mode** — per-gate auto-approval for `dw:flow` convenience gates (scope/plan/changes). Safety hard-stops never relax (Guards, GATE D on a Critical finding, GATE B). Config `workflow.trust.{enabled,profile,auto_approve,max_auto_subtasks,require_evidence}`; one-shot `/dw:flow --trust`. Profiles: `solo-night`, `reviewed-team`.
|
|
45
|
+
- **Overnight Autopilot** — `dw goal --auto=full` + Trust Mode (scheduled by your own cron/CI; recipe `.dw/core/templates/autopilot-cron.sh`). Safe-park on ambiguity, budget-bounded, **stop-before-push**.
|
|
46
|
+
- **CLI:** `dw trust status|gate` · `dw autopilot preflight|postflight` · `dw overnight digest`.
|
|
47
|
+
- Methodology behind it: `.dw/core/HARNESS.md` (multi-agent quality patterns).
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
40
51
|
## Session Start
|
|
41
52
|
|
|
42
53
|
1. Read `.dw/tasks/ACTIVE.md` — single source of truth for team state
|
|
@@ -97,11 +108,11 @@ dw agent release <claim-id> # clean exit
|
|
|
97
108
|
|
|
98
109
|
All dw skills invoke via `/dw:{name}` (colon namespace separator).
|
|
99
110
|
|
|
100
|
-
Core workflow: `/dw:flow` · `/dw:task-init` · `/dw:research` · `/dw:plan` · `/dw:execute` · `/dw:commit` · `/dw:handoff`
|
|
111
|
+
Core workflow: `/dw:flow` (`--trust` for Trust Mode gates) · `/dw:task-init` · `/dw:research` · `/dw:plan` · `/dw:execute` · `/dw:commit` · `/dw:handoff`
|
|
101
112
|
|
|
102
113
|
`/dw:plan` includes **Quick Debate** (red/blue self-critique): default ON for `thorough`, auto-trigger on high-stakes signals for `standard`, off for `quick`. Override via `--debate` / `--no-debate` / `--debate-deep`.
|
|
103
114
|
|
|
104
|
-
Goals (ADR-0010/0016): `/dw:goal` (outcome-driven pursuit loop — drive Goal tới KR, leo thang tư duy khi kẹt; `--auto` long-horizon) · `/dw:goal-sync` (reactive sync khi human pivot)
|
|
115
|
+
Goals (ADR-0010/0016): `/dw:goal` (outcome-driven pursuit loop — drive Goal tới KR, leo thang tư duy khi kẹt; `--auto` long-horizon; `--auto=full` + Trust Mode = overnight autopilot, ADR-0023) · `/dw:goal-sync` (reactive sync khi human pivot)
|
|
105
116
|
|
|
106
117
|
Decisions: `/dw:decision [title]` — create ADR
|
|
107
118
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dw:flow
|
|
3
3
|
description: "Orchestrator: chạy toàn bộ workflow từ đầu đến cuối cho một task, tự động kết nối các phases, dừng tại các human checkpoints để confirm/feedback. Mạnh nhất khi bạn muốn AI tự drive cả task."
|
|
4
|
-
argument-hint: "[task-name] hoặc DW_DEPTH=[depth] [task-name]"
|
|
4
|
+
argument-hint: "[task-name] [--trust | --trust=scope,plan,changes] hoặc DW_DEPTH=[depth] [task-name]"
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# dw-flow — Full Task Workflow Orchestrator
|
|
@@ -113,9 +113,42 @@ Khi đọc và follow bất kỳ SKILL.md nào bên dưới, áp dụng các quy
|
|
|
113
113
|
|
|
114
114
|
---
|
|
115
115
|
|
|
116
|
+
## Trust Mode (ADR-0022) — auto-approve convenience gates
|
|
117
|
+
|
|
118
|
+
Trust Mode lets the user pre-authorize *convenience* gates so flow runs with less (or no) stopping. **OFF by default** — when off, behave exactly as before (stop at every gate).
|
|
119
|
+
|
|
120
|
+
**At each gate, BEFORE stopping, ask the CLI for a deterministic decision:**
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
dw trust gate <name> [--trust "$FLAG"] [--task <task>] [--critical] [--evidence '<json>']
|
|
124
|
+
# <name>: scope (GATE A/Q1) · plan (GATE C) · changes (GATE D/Q2) · arch (GATE B)
|
|
125
|
+
# --trust: pass the run's --trust flag value if the user gave one (true | "scope,plan")
|
|
126
|
+
# --task: the task name (recorded in the audit event)
|
|
127
|
+
# --critical: pass when GATE D and a Critical review finding exists
|
|
128
|
+
# --evidence: PREFERRED for GATE D — the basis (EVD verify), e.g.
|
|
129
|
+
# '{"tests":{"passed":385,"failed":2,"exit":0},"review":{"critical":0,"warning":1},"diff":{"files":2,"insertions":41,"deletions":7,"within_scope":true}}'
|
|
130
|
+
# When evidence is supplied, the CLI derives Critical/red-tests from it (stronger than --critical).
|
|
131
|
+
# exit 0 → AUTO-APPROVE this gate
|
|
132
|
+
# exit 10 → MANUAL stop required (show the gate as usual)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
- **exit 0 (auto-approve):** do NOT stop. Print one line `⚡ auto-approved GATE <X> (trust) — <reason>` and continue. The CLI records the `gate_auto_approved` audit event (with your evidence) — you do NOT log it by hand.
|
|
136
|
+
- **exit 10 (manual):** show the gate normally and wait, exactly as today.
|
|
137
|
+
|
|
138
|
+
> **Honesty note (enforcement model):** `arch`/GATE B and the Guard hooks are *structural* — they can't be relaxed. The **Critical-on-changes** stop is *cooperative*: it only fires if you pass `--critical` or (better) an `--evidence` object that shows the real `review.critical` count. Always pass evidence for GATE D so the stop doesn't depend on you remembering a flag. Evidence is evaluated **only for GATE D (`changes`)** — it has no effect on `scope`/`plan` gates (those approve intent, not test results).
|
|
139
|
+
|
|
140
|
+
**Never relaxed — these stay manual regardless of Trust Mode (the CLI enforces this, do not second-guess it):**
|
|
141
|
+
- `arch` / GATE B (Tech Lead architecture sign-off) — always exit 10.
|
|
142
|
+
- `changes` / GATE D when a **Critical** review finding exists — always exit 10. (Pass `--critical`.)
|
|
143
|
+
- The Guard hooks (`privacy-block`, `pre-commit-gate` secret scan) run independently of gates and are never affected.
|
|
144
|
+
|
|
145
|
+
> If the user passed `--trust` (or `--trust=scope,plan`) on this `/dw:flow` run, thread it into every `dw trust gate` call as the `--trust` value (one-shot, this run only). Otherwise the CLI falls back to `workflow.trust` config.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
116
149
|
## CHECKPOINTS (Human Gates)
|
|
117
150
|
|
|
118
|
-
Tại mỗi GATE, **dừng lại** và hiển thị:
|
|
151
|
+
Tại mỗi GATE, **dừng lại** (trừ khi Trust Mode auto-approve — xem trên) và hiển thị:
|
|
119
152
|
|
|
120
153
|
```
|
|
121
154
|
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
@@ -145,11 +145,32 @@ Tự chủ là một **núm xoay 3 nấc**, không phải bật/tắt. Bắt đ
|
|
|
145
145
|
|
|
146
146
|
**Bất biến ở mọi nấc:**
|
|
147
147
|
- Hard-stop của Termination Contract (irreversible boundary, no-progress guard, ladder L5, wait-gated) **không bao giờ bị nới**.
|
|
148
|
-
- Việc task
|
|
148
|
+
- Việc task đi qua human gate của `dw:flow` (GATE C/D) — TRỪ khi user bật **Trust Mode** (ADR-0022) thì các gate tiện lợi được auto-approve. Kể cả vậy, hard-stop an toàn (Guards, Critical, GATE B) vẫn dừng. Không bật Trust = loop vẫn dừng ở GATE C/D như cũ.
|
|
149
149
|
- Càng lên nấc cao, journal `goal-loop.md` càng phải ghi đầy đủ (để human audit lại chuỗi quyết định đã tự chạy).
|
|
150
150
|
|
|
151
151
|
**Lộ trình tự động hoá sâu hơn (P2/P3, telemetry-gated):** đo KR auto-measurable tự động qua CLI helper (`dw goal gap`), rồi tới adapter chạy `test_command`/đếm artifact và tự ghi `current` — giảm dần phần human phải đo tay. Xem ADR-0016 Phasing.
|
|
152
152
|
|
|
153
|
+
## Overnight Autopilot — chạy đêm, review sáng (ADR-0023)
|
|
154
|
+
|
|
155
|
+
Khi chạy `--auto=full` **kèm Trust Mode bật** (qua OS/CI cron của user, ví dụ `dw goal --auto=full --trust`), loop trở thành autopilot không người trông.
|
|
156
|
+
|
|
157
|
+
**INPUT contract — chạy `dw autopilot preflight --goal <id> --max-iter <n>` TRƯỚC khi bắt đầu.** Exit ≠ 0 → KHÔNG chạy (tree bẩn / budget vô hạn / trust blanket-unbounded). Đây là "fail trước khi bắt đầu". (Preflight là *cooperative*: gọi `dw goal --auto=full` trực tiếp từ shell sẽ bỏ qua nó — cron template `.dw/core/templates/autopilot-cron.sh` là đường an toàn được khuyến nghị.) Khi gọi `dw trust gate` trong vòng lặp, truyền `--run-count <n>` (số gate đã auto-approve) để `max_auto_subtasks` được enforce thật.
|
|
158
|
+
|
|
159
|
+
Áp thêm **run contract** trong lúc chạy:
|
|
160
|
+
|
|
161
|
+
1. **Safe-park-on-ambiguity — KHÔNG đoán.** Gặp quyết định Trust Mode không bao trùm (Critical finding, thao tác irreversible/phá huỷ, hoặc design fork không có winner rõ) → **không tự quyết**. Ghi một event `parked` vào `.dw/events-global.jsonl`:
|
|
162
|
+
```
|
|
163
|
+
{"event":"parked","item":"<chỗ kẹt>","question":"<câu cần human>","options":["A","B"]}
|
|
164
|
+
```
|
|
165
|
+
rồi tiếp tục phần *an toàn* còn lại. Parked items là phần human xử lý buổi sáng.
|
|
166
|
+
2. **Mỗi subtask xong → log** `{"event":"subtask_completed","subtask":"ST-x","commit":"<sha>","summary":"..."}`. Mỗi hard-stop → `{"event":"hard_stop","gate":"...","reason":"..."}`.
|
|
167
|
+
3. **Budget bound → dừng graceful.** Chạm `--max-iter` / `workflow.trust.max_auto_subtasks` / hết ngân sách → ghi `{"event":"overnight_wrapup","stop_reason":"budget|done|no-progress"}`, KHÔNG chạy nóng để ép xong.
|
|
168
|
+
4. **EVD verify ở GATE D.** Khi gọi `dw trust gate changes`, LUÔN kèm `--evidence '{"tests":{...},"review":{"critical":N,...},"diff":{...}}'` để quyết định auto-approve dựa trên *bằng chứng* (tests xanh, 0 Critical, diff trong scope), không phải lời hứa. Evidence được ghi vào digest dưới dạng "evidence card".
|
|
169
|
+
5. **OUTPUT contract — cuối run:** chạy `dw autopilot postflight --require-wrapup` (kiểm digest tồn tại · có wrap-up · local-only) rồi `dw overnight digest` → tạo `OVERNIGHT.md` (đọc nguội buổi sáng: verdict · done+SHA · auto-approved+evidence · ⏸ parked-for-you · 🛑 hard-stops · review-next).
|
|
170
|
+
6. **Dừng trước push.** Autopilot commit cục bộ; push/PR để human. (Kỷ luật no-auto-push.)
|
|
171
|
+
|
|
172
|
+
> Scheduling KHÔNG nằm trong toolkit — user tự đặt cron/at/CI gọi lệnh autopilot (ADR-0021: không nhét daemon vào binary).
|
|
173
|
+
|
|
153
174
|
## State bền vững giữa các session — `goal-loop.md`
|
|
154
175
|
|
|
155
176
|
Khi loop kéo dài nhiều session HOẶC chạy `--auto`, ghi annex `.dw/goals/{goal-id}/goal-loop.md`
|
|
@@ -22,6 +22,30 @@
|
|
|
22
22
|
"type": "string",
|
|
23
23
|
"enum": ["quick", "standard", "thorough"],
|
|
24
24
|
"default": "standard"
|
|
25
|
+
},
|
|
26
|
+
"trust": {
|
|
27
|
+
"type": "object",
|
|
28
|
+
"additionalProperties": false,
|
|
29
|
+
"description": "Trust Mode (ADR-0022) — opt-in auto-approval for dw:flow convenience gates. Off by default. Guards + Critical findings + GATE B are never relaxed.",
|
|
30
|
+
"properties": {
|
|
31
|
+
"profile": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"enum": ["solo-night", "reviewed-team"],
|
|
34
|
+
"description": "Named trust preset; explicit keys below override it (ADR-0023)"
|
|
35
|
+
},
|
|
36
|
+
"enabled": { "type": "boolean", "default": false },
|
|
37
|
+
"auto_approve": {
|
|
38
|
+
"type": "object",
|
|
39
|
+
"additionalProperties": false,
|
|
40
|
+
"properties": {
|
|
41
|
+
"scope": { "type": "boolean", "default": false },
|
|
42
|
+
"plan": { "type": "boolean", "default": false },
|
|
43
|
+
"changes": { "type": "boolean", "default": false }
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"max_auto_subtasks": { "type": "integer", "minimum": 0, "default": 0 },
|
|
47
|
+
"require_evidence": { "type": "boolean", "default": false, "description": "GATE D refuses to auto-approve without an --evidence object" }
|
|
48
|
+
}
|
|
25
49
|
}
|
|
26
50
|
}
|
|
27
51
|
},
|
package/.dw/config/dw.config.yml
CHANGED
|
@@ -18,6 +18,20 @@ workflow:
|
|
|
18
18
|
# standard : 3-5 files, module mới, unfamiliar code
|
|
19
19
|
# thorough : 6+ files, API contract changes, DB schema, security
|
|
20
20
|
|
|
21
|
+
# Trust Mode (ADR-0022) — opt-in auto-approval for dw:flow convenience gates.
|
|
22
|
+
# OFF by default = every gate is manual (today's behaviour). Guards
|
|
23
|
+
# (privacy-block, secret-scan), Critical review findings, and GATE B (TL
|
|
24
|
+
# architecture sign-off) are NEVER relaxed. One-shot: `/dw:flow --trust`.
|
|
25
|
+
trust:
|
|
26
|
+
# profile: solo-night # named preset (solo-night | reviewed-team); explicit keys below override it
|
|
27
|
+
enabled: false
|
|
28
|
+
auto_approve:
|
|
29
|
+
scope: false # GATE A / Q1 — confirm scope
|
|
30
|
+
plan: false # GATE C — approve plan
|
|
31
|
+
changes: false # GATE D / Q2 — approve changes (never when Critical)
|
|
32
|
+
max_auto_subtasks: 0 # 0 = unbounded once enabled; >0 caps an unattended run
|
|
33
|
+
require_evidence: false # when true, GATE D won't auto-approve without --evidence
|
|
34
|
+
|
|
21
35
|
# --- Team -------------------------------------------------------------------
|
|
22
36
|
team:
|
|
23
37
|
roles:
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# HARNESS — multi-agent quality patterns
|
|
2
|
+
|
|
3
|
+
A small playbook for using more than one agent (or one agent more than once) to reach a
|
|
4
|
+
**better-verified** answer than a single pass — not a bigger one. Vendor- and runtime-neutral.
|
|
5
|
+
|
|
6
|
+
The rule that governs all of it:
|
|
7
|
+
|
|
8
|
+
> **Judge a harness by verified outcome per unit cost, not by sophistication.** Use a harness
|
|
9
|
+
> only when an independent pass is likely to change a decision, catch a costly error, or produce
|
|
10
|
+
> evidence a single pass would not. If the second pass only adds volume, ceremony, or confidence
|
|
11
|
+
> theater — stop.
|
|
12
|
+
|
|
13
|
+
These patterns improve **correctness and judgment**, not throughput. They do not, by themselves,
|
|
14
|
+
make delivery faster.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## The patterns
|
|
19
|
+
|
|
20
|
+
### 1. Fan-out → judge → review (decorrelated adjudication)
|
|
21
|
+
Split an independent work-list (links, findings, files, candidates) across N agents, then run
|
|
22
|
+
each result through a *second, independent* judge before committing it.
|
|
23
|
+
- **When:** a set of items each needing an assessment, where a first-pass error is plausible.
|
|
24
|
+
- **Cost:** N agents + a judge pass. Cheaper model for the finders, a stronger one for the judge.
|
|
25
|
+
- **Requirement:** the judge must have access to the **source of truth** and must cite the
|
|
26
|
+
deciding fact. Do not adjudicate from summaries when the underlying artifact is inspectable —
|
|
27
|
+
artifact-first beats transcript-first.
|
|
28
|
+
- **Why it pays:** the judge catches first-pass mistakes the producer can't see — e.g. flipping a
|
|
29
|
+
wrong "remove" verdict back to "keep", or accepting an item while flagging that its *underlying
|
|
30
|
+
data* is what's actually wrong.
|
|
31
|
+
|
|
32
|
+
### 2. Cold review before done (fresh-context adversarial check)
|
|
33
|
+
Before reporting substantive work complete, run a fresh, read-only reviewer whose job is to
|
|
34
|
+
**falsify the "done" claim** — using source, diff, build/test output, and the real user path.
|
|
35
|
+
- **When:** any non-trivial change, before you say "done".
|
|
36
|
+
- **Cost:** one agent. Almost always worth it.
|
|
37
|
+
- **Why it pays:** a fresh context with an adversarial brief catches what the author rationalized
|
|
38
|
+
past. (Distinct from ordinary self-review: a *different* context with a falsification brief, not
|
|
39
|
+
the author re-reading their own work.)
|
|
40
|
+
|
|
41
|
+
### 3. Evidence council for hard calls
|
|
42
|
+
For a genuinely ambiguous, high-stakes decision, spawn N *independent* assessors — ideally across
|
|
43
|
+
different models and **different briefs** — each reporting findings with reasoning.
|
|
44
|
+
- **Votes are advisory; the orchestrator decides from evidence:** tests, source facts, user
|
|
45
|
+
impact, constraints, explicit uncertainty. A 2-1 vote with weak evidence should lose to one
|
|
46
|
+
dissenting finding backed by a reproducible failure.
|
|
47
|
+
- **When:** the call is hard *and* expensive to get wrong. Reserve it.
|
|
48
|
+
- **Why it pays:** decorrelates single-agent error — but only if the assessors are genuinely
|
|
49
|
+
independent. A majority vote over a shared, stale summary just amplifies a common blind spot.
|
|
50
|
+
|
|
51
|
+
### 4. Outside-in dogfood (a release gate)
|
|
52
|
+
Use the product exactly as a real user would — install it, drive it through an agent, check the
|
|
53
|
+
answers are *useful*, not merely non-erroring — separate from the unit suite.
|
|
54
|
+
- **When:** a release gate for installable tools and user-facing workflows; ongoing thereafter.
|
|
55
|
+
- **Why it pays:** catches what unit tests structurally cannot — a broken install path, a
|
|
56
|
+
confusing first-run response, an empty-looking result. The failures users hit first.
|
|
57
|
+
|
|
58
|
+
### 5. Lessons-as-memory (the learning loop)
|
|
59
|
+
Record each notable failure with its **detection method, its fix, and the condition that would
|
|
60
|
+
make the lesson obsolete**; recall and apply the accumulation next cycle. Prune what proves wrong.
|
|
61
|
+
- **When:** always — the cheapest pattern here.
|
|
62
|
+
- **Why it pays:** specific, sourced lessons compound. Vague ones ("use more agents") become
|
|
63
|
+
cargo-cult prompts; the valuable memory is "this exact failure escaped this exact gate."
|
|
64
|
+
|
|
65
|
+
### 6. Handoff-as-continuity (for interrupted or multi-agent work)
|
|
66
|
+
When a run may stop, hit a limit, or pass work to another agent, write a pickup-ready handoff:
|
|
67
|
+
current state, the exact next command/action, files touched, verification already run, known
|
|
68
|
+
blockers, and human-only gates.
|
|
69
|
+
- **When:** long runs, usage-limit risk, or handing off to a peer.
|
|
70
|
+
- **Why it pays:** it is what makes an interruption *recoverable*. A stopped or usage-limited
|
|
71
|
+
agent cannot be woken by a message — only its own runtime or a human resumes it; the handoff is
|
|
72
|
+
what lets that resumption be clean.
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## The decision rule (read before spawning anything)
|
|
77
|
+
|
|
78
|
+
1. **Prefer in-context fan-out over live peer-coordination.** A workflow that fans out agents
|
|
79
|
+
inside one orchestrated run is cheap, deterministic, and has no liveness gap. Coordinating two
|
|
80
|
+
independently-running agent *sessions* (a shared bus, claims) is expensive and fragile, and a
|
|
81
|
+
stopped peer can't be woken by a message. Use live peer-coordination only when you genuinely
|
|
82
|
+
need two running runtimes.
|
|
83
|
+
2. **Match the pattern to the stakes.** Cold review for most things; a council only for the hard,
|
|
84
|
+
expensive-to-get-wrong calls. Every spawn costs.
|
|
85
|
+
3. **Pick a task-specific conservative default before you start.** For deletion/curation,
|
|
86
|
+
uncertainty usually means *keep and flag*. For publish, credentials, privacy, security, and
|
|
87
|
+
destructive actions, uncertainty means *block or escalate*.
|
|
88
|
+
4. **Have a stop condition.** If two independent passes converge with evidence and no unresolved
|
|
89
|
+
high-impact uncertainty, stop spawning. Passes past convergence are cost without signal.
|
|
90
|
+
5. **Raise conservatism when you remove the human.** Auto-approval and unattended runs are
|
|
91
|
+
where a harness pays off most and where a wrong call is least recoverable. Keep a set of
|
|
92
|
+
hard-stops that autonomy cannot relax (secrets, destructive/irreversible ops, a Critical
|
|
93
|
+
finding), and on an ambiguous *irreversible* call, **park it with the question and the
|
|
94
|
+
options you see — do not guess.** Unattended should be *more* conservative than supervised,
|
|
95
|
+
not less.
|
|
96
|
+
|
|
97
|
+
### Independence checklist
|
|
98
|
+
Before treating agents as independent, check:
|
|
99
|
+
- Did each pass inspect the source artifact, not only another agent's summary?
|
|
100
|
+
- Did the reviewer have a different brief from the producer?
|
|
101
|
+
- Are uncertainty and assumptions recorded?
|
|
102
|
+
- Is there a conservative default for ambiguous cases?
|
|
103
|
+
- Is there a stop condition to prevent review loops?
|
|
104
|
+
|
|
105
|
+
### Do NOT use a harness when
|
|
106
|
+
- The task is trivial and reversible.
|
|
107
|
+
- The answer is mechanically testable with one command.
|
|
108
|
+
- The extra agent cannot inspect better evidence than the first.
|
|
109
|
+
- The decision is low-stakes and cheaper to fix later.
|
|
110
|
+
- You are using more agents to avoid making a product or authority decision.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Honest boundaries
|
|
115
|
+
|
|
116
|
+
- **This is a *learning* harness, not a *self-evolving* one.** Lessons accumulate because a human
|
|
117
|
+
or agent curates them — there is no autonomous measure→fix loop running unattended. Don't
|
|
118
|
+
oversell autonomy; it rises only as a measured error-rate falls.
|
|
119
|
+
- **The realtime multi-agent bus is out of scope for this doc.** Treat a shared-file bus as an
|
|
120
|
+
async coordination log and audit trail — not a scheduler, lock manager, or wake-up channel.
|
|
121
|
+
Turn-based agents can emit during a run and ingest at turn start; a stopped or usage-limited peer
|
|
122
|
+
will not react until its own runtime or a human resumes it. For more than one writer, require
|
|
123
|
+
per-agent worktrees **or** orchestrator-assigned disjoint write scopes (non-overlap is the
|
|
124
|
+
cheapest prevention; worktrees are the strongest). Before relying on a bus for active
|
|
125
|
+
coordination, add an enforced pre-write/pre-commit choke point for claimed paths, a serialized
|
|
126
|
+
event substrate such as SQLite-WAL — which fixes ordering/durability but **not** shared-tree
|
|
127
|
+
write races — turn-start ingest with cursors, and a separate liveness/supervisor story if
|
|
128
|
+
automatic reactivation is a goal.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Where this sits in the 5-pillar model
|
|
133
|
+
|
|
134
|
+
These patterns are **Records** (capture what was learned) and **Tunes** (knobs the team turns on
|
|
135
|
+
per task). They deliver value without the heavier Surfaces/Bridges runtime — a single agent using
|
|
136
|
+
**Cold review** + **Lessons-as-memory** is already better off.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## How dw-kit implements these (non-normative, repo-specific)
|
|
141
|
+
|
|
142
|
+
> This appendix maps the neutral patterns above onto dw-kit features, for readers inside this
|
|
143
|
+
> repo. It is **not** part of the portable playbook — a vendor-neutral export may delete it.
|
|
144
|
+
|
|
145
|
+
| Pattern | dw-kit surface |
|
|
146
|
+
|---------|----------------|
|
|
147
|
+
| Fan-out → judge | Agent OS claims (`dw agent claim`, ADR-0009) cover the fan-out / disjoint-scope half (cooperative, post-hoc conflict detection, *not* enforcement); the judge pass is the orchestrator merge + `/dw:review` |
|
|
148
|
+
| Cold review before done | `/dw:review` (fresh-context falsification pass), orchestrated as `/dw:flow`'s Review phase |
|
|
149
|
+
| Evidence council | `/dw:plan` Quick Debate (red/blue) + `dw trust gate --evidence` (EVD, ADR-0022/0023) — votes advisory, evidence decides |
|
|
150
|
+
| Outside-in dogfood | manual install-and-drive dogfood practice (e.g. the G-dogfood-v1.7 friction journal) — a discipline, not an automated gate |
|
|
151
|
+
| Lessons-as-memory | `task.md` Section 5 Friction Journal + ADR "Consequences" + `.dw/research/` notes (the host auto-memory store is a Claude Code feature, not dw-kit) |
|
|
152
|
+
| Handoff-as-continuity | `/dw:handoff` + `task.md` Section 5 + the overnight digest (ADR-0023) |
|
|
153
|
+
| Raise conservatism off-human | Trust Mode non-relaxable hard-stops (ADR-0022) + overnight safe-park (ADR-0023) |
|
|
154
|
+
|
|
155
|
+
**See also:** `QUALITY.md` — the 4-layer quality framework; HARNESS is the multi-agent
|
|
156
|
+
mechanics behind its Layer 3 (Cross-Review) and Layer 4 (gates). `AGENTS.md` — agent
|
|
157
|
+
report/handoff conventions used by pattern 6.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/gate_auto_approved.schema.json",
|
|
4
|
+
"title": "DW Event: gate_auto_approved",
|
|
5
|
+
"description": "Category: trust-autopilot. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"ts": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"format": "date-time",
|
|
11
|
+
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
|
|
12
|
+
"description": "ISO 8601 UTC timestamp (envelope, set by writer)"
|
|
13
|
+
},
|
|
14
|
+
"event": {
|
|
15
|
+
"type": "string",
|
|
16
|
+
"const": "gate_auto_approved",
|
|
17
|
+
"description": "Event name (envelope)"
|
|
18
|
+
},
|
|
19
|
+
"gate": {
|
|
20
|
+
"type": "string"
|
|
21
|
+
},
|
|
22
|
+
"actor": {
|
|
23
|
+
"type": "string"
|
|
24
|
+
},
|
|
25
|
+
"task": {},
|
|
26
|
+
"reason": {},
|
|
27
|
+
"evidence": {}
|
|
28
|
+
},
|
|
29
|
+
"required": [
|
|
30
|
+
"ts",
|
|
31
|
+
"event",
|
|
32
|
+
"gate",
|
|
33
|
+
"actor"
|
|
34
|
+
],
|
|
35
|
+
"additionalProperties": true
|
|
36
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/hard_stop.schema.json",
|
|
4
|
+
"title": "DW Event: hard_stop",
|
|
5
|
+
"description": "Category: trust-autopilot. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"ts": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"format": "date-time",
|
|
11
|
+
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
|
|
12
|
+
"description": "ISO 8601 UTC timestamp (envelope, set by writer)"
|
|
13
|
+
},
|
|
14
|
+
"event": {
|
|
15
|
+
"type": "string",
|
|
16
|
+
"const": "hard_stop",
|
|
17
|
+
"description": "Event name (envelope)"
|
|
18
|
+
},
|
|
19
|
+
"reason": {
|
|
20
|
+
"type": "string"
|
|
21
|
+
},
|
|
22
|
+
"gate": {
|
|
23
|
+
"type": "string"
|
|
24
|
+
},
|
|
25
|
+
"blocker": {
|
|
26
|
+
"type": "string"
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
"required": [
|
|
30
|
+
"ts",
|
|
31
|
+
"event",
|
|
32
|
+
"reason"
|
|
33
|
+
],
|
|
34
|
+
"additionalProperties": true
|
|
35
|
+
}
|
|
@@ -4,14 +4,15 @@
|
|
|
4
4
|
"title": "DW Event Schema v1.0 — Index",
|
|
5
5
|
"description": "Generated from src/lib/event-schema.mjs EVENT_CATALOGUE by scripts/generate-event-schemas.mjs. Do not edit by hand; regenerate via 'npm run gen:event-schemas'.",
|
|
6
6
|
"schema_version": "1.0.0",
|
|
7
|
-
"generated_at": "2026-
|
|
7
|
+
"generated_at": "2026-07-02T13:35:29Z",
|
|
8
8
|
"spec_url": "https://github.com/dv-workflow/dv-workflow/blob/main/docs/specs/dw-event-schema-v1.0.md",
|
|
9
9
|
"protocol_url": "https://github.com/dv-workflow/dv-workflow/blob/main/docs/specs/dw-adapter-protocol.md",
|
|
10
|
-
"total_events":
|
|
10
|
+
"total_events": 38,
|
|
11
11
|
"categories": [
|
|
12
12
|
"debate",
|
|
13
13
|
"goal",
|
|
14
14
|
"session-lifecycle",
|
|
15
|
+
"trust-autopilot",
|
|
15
16
|
"voice-action",
|
|
16
17
|
"voice-orchestrator"
|
|
17
18
|
],
|
|
@@ -46,6 +47,11 @@
|
|
|
46
47
|
"category": "debate",
|
|
47
48
|
"file": "debate_started.schema.json"
|
|
48
49
|
},
|
|
50
|
+
{
|
|
51
|
+
"name": "gate_auto_approved",
|
|
52
|
+
"category": "trust-autopilot",
|
|
53
|
+
"file": "gate_auto_approved.schema.json"
|
|
54
|
+
},
|
|
49
55
|
{
|
|
50
56
|
"name": "goal_archived",
|
|
51
57
|
"category": "goal",
|
|
@@ -81,6 +87,11 @@
|
|
|
81
87
|
"category": "goal",
|
|
82
88
|
"file": "goal_task_unlinked.schema.json"
|
|
83
89
|
},
|
|
90
|
+
{
|
|
91
|
+
"name": "hard_stop",
|
|
92
|
+
"category": "trust-autopilot",
|
|
93
|
+
"file": "hard_stop.schema.json"
|
|
94
|
+
},
|
|
84
95
|
{
|
|
85
96
|
"name": "orchestrator_cancelled",
|
|
86
97
|
"category": "voice-action",
|
|
@@ -141,6 +152,16 @@
|
|
|
141
152
|
"category": "voice-orchestrator",
|
|
142
153
|
"file": "orchestrator_timeout.schema.json"
|
|
143
154
|
},
|
|
155
|
+
{
|
|
156
|
+
"name": "overnight_wrapup",
|
|
157
|
+
"category": "trust-autopilot",
|
|
158
|
+
"file": "overnight_wrapup.schema.json"
|
|
159
|
+
},
|
|
160
|
+
{
|
|
161
|
+
"name": "parked",
|
|
162
|
+
"category": "trust-autopilot",
|
|
163
|
+
"file": "parked.schema.json"
|
|
164
|
+
},
|
|
144
165
|
{
|
|
145
166
|
"name": "reconciled",
|
|
146
167
|
"category": "session-lifecycle",
|
|
@@ -180,6 +201,11 @@
|
|
|
180
201
|
"name": "stopped",
|
|
181
202
|
"category": "session-lifecycle",
|
|
182
203
|
"file": "stopped.schema.json"
|
|
204
|
+
},
|
|
205
|
+
{
|
|
206
|
+
"name": "subtask_completed",
|
|
207
|
+
"category": "trust-autopilot",
|
|
208
|
+
"file": "subtask_completed.schema.json"
|
|
183
209
|
}
|
|
184
210
|
]
|
|
185
211
|
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/overnight_wrapup.schema.json",
|
|
4
|
+
"title": "DW Event: overnight_wrapup",
|
|
5
|
+
"description": "Category: trust-autopilot. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"ts": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"format": "date-time",
|
|
11
|
+
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
|
|
12
|
+
"description": "ISO 8601 UTC timestamp (envelope, set by writer)"
|
|
13
|
+
},
|
|
14
|
+
"event": {
|
|
15
|
+
"type": "string",
|
|
16
|
+
"const": "overnight_wrapup",
|
|
17
|
+
"description": "Event name (envelope)"
|
|
18
|
+
},
|
|
19
|
+
"stop_reason": {
|
|
20
|
+
"type": "string"
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"required": [
|
|
24
|
+
"ts",
|
|
25
|
+
"event",
|
|
26
|
+
"stop_reason"
|
|
27
|
+
],
|
|
28
|
+
"additionalProperties": true
|
|
29
|
+
}
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/parked.schema.json",
|
|
4
|
+
"title": "DW Event: parked",
|
|
5
|
+
"description": "Category: trust-autopilot. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"ts": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"format": "date-time",
|
|
11
|
+
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
|
|
12
|
+
"description": "ISO 8601 UTC timestamp (envelope, set by writer)"
|
|
13
|
+
},
|
|
14
|
+
"event": {
|
|
15
|
+
"type": "string",
|
|
16
|
+
"const": "parked",
|
|
17
|
+
"description": "Event name (envelope)"
|
|
18
|
+
},
|
|
19
|
+
"item": {
|
|
20
|
+
"type": "string"
|
|
21
|
+
},
|
|
22
|
+
"question": {
|
|
23
|
+
"type": "string"
|
|
24
|
+
},
|
|
25
|
+
"options": {
|
|
26
|
+
"type": "array",
|
|
27
|
+
"items": {
|
|
28
|
+
"type": "string"
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"required": [
|
|
33
|
+
"ts",
|
|
34
|
+
"event",
|
|
35
|
+
"item",
|
|
36
|
+
"question"
|
|
37
|
+
],
|
|
38
|
+
"additionalProperties": true
|
|
39
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://github.com/dv-workflow/dv-workflow/schemas/events/subtask_completed.schema.json",
|
|
4
|
+
"title": "DW Event: subtask_completed",
|
|
5
|
+
"description": "Category: trust-autopilot. See docs/specs/dw-event-schema-v1.0.md §5 for narrative.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"ts": {
|
|
9
|
+
"type": "string",
|
|
10
|
+
"format": "date-time",
|
|
11
|
+
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d+)?Z$",
|
|
12
|
+
"description": "ISO 8601 UTC timestamp (envelope, set by writer)"
|
|
13
|
+
},
|
|
14
|
+
"event": {
|
|
15
|
+
"type": "string",
|
|
16
|
+
"const": "subtask_completed",
|
|
17
|
+
"description": "Event name (envelope)"
|
|
18
|
+
},
|
|
19
|
+
"subtask": {
|
|
20
|
+
"type": "string"
|
|
21
|
+
},
|
|
22
|
+
"commit": {
|
|
23
|
+
"type": "string"
|
|
24
|
+
},
|
|
25
|
+
"summary": {
|
|
26
|
+
"type": "string"
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
"required": [
|
|
30
|
+
"ts",
|
|
31
|
+
"event",
|
|
32
|
+
"subtask"
|
|
33
|
+
],
|
|
34
|
+
"additionalProperties": true
|
|
35
|
+
}
|