Skip to content

Commit 09aecb5

Browse files
easeleasel
committed
Add agent quorum implementation docs
1 parent 73cbfec commit 09aecb5

5 files changed

Lines changed: 265 additions & 0 deletions

File tree

‎config.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"type": "rig",
3+
"version": 1,
4+
"name": "dun",
5+
"state": "active",
6+
"repo": "https://github.com/easel/dun.git",
7+
"git_url": "https://github.com/easel/dun.git",
8+
"default_branch": "main",
9+
"created_at": "2026-02-03T11:47:00.19750982-05:00",
10+
"beads": {
11+
"prefix": "dun"
12+
},
13+
"git": {
14+
"origin": "https://github.com/easel/dun.git",
15+
"upstream": "https://github.com/easel/dun.git"
16+
}
17+
}

‎docs/helix/01-frame/user-stories/US-015-agent-quorum-implementation.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
dun:
3+
id: US-015
4+
depends_on:
5+
- F-018
6+
---
7+
# US-015: Implement Agent Quorum + Synthesis Commands
8+
9+
As a maintainer, I want one-shot quorum and synthesis commands that reuse the
10+
loop quorum engine so I can obtain consensus or a merged result without
11+
running a full iteration loop.
12+
13+
## Acceptance Criteria
14+
15+
- `dun quorum` parses `--task`, `--quorum`, `--harnesses`, and conflict flags.
16+
- `dun synth` is shorthand for `dun quorum --synthesize`.
17+
- Harness specs support `name@persona` and pass persona names through to the
18+
harness layer.
19+
- Synthesis mode runs a meta-harness and returns merged output.
20+
- Quorum summary metadata is emitted deterministically.
21+
- `dun loop --quorum` uses the same quorum engine as one-shot commands.

‎docs/helix/02-design/technical-designs/TD-015-agent-quorum-implementation.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
dun:
3+
id: TD-015
4+
depends_on:
5+
- US-015
6+
---
7+
# Technical Design: TD-015 Agent Quorum + Synthesis Commands
8+
9+
## Story Reference
10+
11+
**User Story**: US-015 Implement Agent Quorum + Synthesis Commands
12+
**Parent Feature**: F-018 Agent Quorum
13+
**Solution Design**: SD-011 Agent Quorum
14+
15+
## Goals
16+
17+
- Provide `dun quorum` and `dun synth` as one-shot command surfaces.
18+
- Reuse the existing quorum engine from `dun loop --quorum`.
19+
- Support `name@persona` harness specs and a synthesis meta-harness.
20+
- Emit deterministic quorum summary metadata for automation.
21+
22+
## Non-Goals
23+
24+
- Changing quorum strategies or similarity algorithms beyond the existing spec.
25+
- Introducing a new policy system; rely on existing automation modes.
26+
27+
## Technical Approach
28+
29+
### Implementation Strategy
30+
31+
- Add a dedicated command entry point (`cmd/dun/quorum.go`) that parses flags
32+
and builds a `QuorumConfig` shared with the loop.
33+
- Reuse the quorum execution path in `internal/dun/quorum.go` for both one-shot
34+
and loop modes to keep behavior consistent.
35+
- Extend harness parsing to accept `name@persona` and pass persona names to the
36+
harness layer without interpretation.
37+
- In synthesis mode, run the meta-harness with a deterministic prompt that
38+
merges drafts into a single response.
39+
40+
### Key Decisions
41+
42+
- One-shot commands share the same quorum engine as `dun loop --quorum`.
43+
- Quorum summary output is structured and stable for machine parsing.
44+
- Persona definitions remain owned by the harness/DDX layer.
45+
46+
## Component Changes
47+
48+
### Components to Modify
49+
50+
- `cmd/dun/main.go`: register `quorum` and `synth` commands.
51+
- `cmd/dun/quorum.go`: flag parsing and command execution.
52+
- `internal/dun/quorum.go`: shared execution path for vote and synthesis.
53+
- `internal/dun/config.go`: default quorum settings and synthesizer config.
54+
- `internal/dun/types.go`: harness spec and synthesizer types.
55+
56+
### New Components
57+
58+
- None (reuse existing quorum and harness code paths).
59+
60+
## Interfaces and Config
61+
62+
- CLI:
63+
- `dun quorum --task "..." --quorum any|majority|unanimous|N --harnesses a,b`
64+
- `dun synth --task "..." --harnesses a,b --synthesizer c@persona`
65+
- Config:
66+
- `.dun/config.yaml` entries under `quorum.*` for defaults.
67+
68+
## Data and State
69+
70+
- No new persistent state; summary metadata is emitted per invocation.
71+
72+
## Testing Approach
73+
74+
- CLI parsing tests for `dun quorum` and `dun synth` flags.
75+
- Unit tests for `name@persona` parsing and synthesizer selection.
76+
- Integration tests for synthesis mode and deterministic summary output.
77+
78+
## Risks and Mitigations
79+
80+
- **Risk**: Inconsistent behavior between loop and one-shot commands.
81+
**Mitigation**: Single shared quorum execution path.
82+
- **Risk**: Non-deterministic summary ordering.
83+
**Mitigation**: Stable sorting and explicit field ordering in outputs.
84+
85+
## Rollout / Compatibility
86+
87+
- Additive commands; no breaking changes to existing loop behavior.

‎docs/helix/03-test/test-plans/TP-015-agent-quorum-implementation.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
dun:
3+
id: TP-015
4+
depends_on:
5+
- TD-011
6+
---
7+
# TP-015: Agent Quorum + Synthesis Implementation Plan
8+
9+
**User Story**: US-011
10+
**Version**: 1.0.0
11+
**Date**: 2026-02-03
12+
**Status**: Draft
13+
**Author**: codex
14+
15+
## 1. Scope
16+
17+
This test plan verifies the implementation-plan specific work in IP-015:
18+
- One-shot quorum commands (`dun quorum`, `dun synth`).
19+
- Persona-aware harness selection (`name@persona`).
20+
- Synthesis meta-harness execution.
21+
- Deterministic quorum summary metadata.
22+
- Shared quorum engine between `dun loop --quorum` and one-shot commands.
23+
24+
## 2. Acceptance Criteria
25+
26+
| ID | Acceptance Criterion |
27+
|----|---------------------|
28+
| AC-1 | `dun quorum` parses `--task`, `--quorum`, `--harnesses`, and conflict flags |
29+
| AC-2 | `dun synth` is a shorthand for `dun quorum --synthesize` |
30+
| AC-3 | `name@persona` parses and is passed through to harness execution |
31+
| AC-4 | Synthesis mode runs a meta-harness and returns merged output |
32+
| AC-5 | Quorum summary metadata is emitted deterministically |
33+
| AC-6 | `dun loop --quorum` uses the same quorum engine as one-shot commands |
34+
35+
## 3. Existing Test Coverage
36+
37+
| AC | Existing Test | File | Status |
38+
|----|---------------|------|--------|
39+
| AC-1 | Quorum flag parsing | `docs/helix/03-test/test-plans/TP-011-agent-quorum.md` | Partial |
40+
| AC-2 | None | - | Missing |
41+
| AC-3 | None | - | Missing |
42+
| AC-4 | None | - | Missing |
43+
| AC-5 | None | - | Missing |
44+
| AC-6 | None | - | Missing |
45+
46+
## 4. Test Gaps
47+
48+
| Gap ID | Description | Priority | Acceptance Criteria |
49+
|--------|-------------|----------|---------------------|
50+
| GAP-015-01 | One-shot command parsing and output tests | P0 | AC-1, AC-2 |
51+
| GAP-015-02 | Persona parsing and passthrough tests | P0 | AC-3 |
52+
| GAP-015-03 | Synthesis mode integration test | P0 | AC-4 |
53+
| GAP-015-04 | Quorum summary metadata determinism | P1 | AC-5 |
54+
| GAP-015-05 | Loop uses shared quorum engine | P1 | AC-6 |
55+
56+
## 5. Proposed Test Cases
57+
58+
### 5.1 CLI Parsing
59+
60+
#### TC-015-01: Quorum command parsing
61+
**File**: `cmd/dun/quorum_test.go`
62+
**Priority**: P0
63+
**Covers**: AC-1
64+
65+
```go
66+
func TestQuorumCommandParsing(t *testing.T) {
67+
// Given: dun quorum --task "spec" --quorum 2 --harnesses a,b
68+
// Then: parsed config includes task, quorum, harnesses
69+
}
70+
```
71+
72+
#### TC-015-02: Synth shorthand parsing
73+
**File**: `cmd/dun/quorum_test.go`
74+
**Priority**: P0
75+
**Covers**: AC-2
76+
77+
```go
78+
func TestSynthCommandShorthand(t *testing.T) {
79+
// Given: dun synth --task "spec" --harnesses a,b --synthesizer a
80+
// Then: synthesize mode is enabled and synthesizer is set
81+
}
82+
```
83+
84+
### 5.2 Persona Parsing
85+
86+
#### TC-015-03: Harness persona parsing
87+
**File**: `internal/dun/quorum_test.go`
88+
**Priority**: P0
89+
**Covers**: AC-3
90+
91+
```go
92+
func TestParseHarnessSpecPersona(t *testing.T) {
93+
// Given: "codex@architect"
94+
// Then: Name=codex, Persona=architect
95+
}
96+
```
97+
98+
### 5.3 Synthesis Mode
99+
100+
#### TC-015-04: Synthesis meta-harness invoked
101+
**File**: `internal/dun/quorum_test.go`
102+
**Priority**: P0
103+
**Covers**: AC-4
104+
105+
```go
106+
func TestSynthesisModeInvokesMetaHarness(t *testing.T) {
107+
// Given: multiple harness drafts
108+
// Then: synthesizer runs and returns merged output
109+
}
110+
```
111+
112+
### 5.4 Summary Metadata
113+
114+
#### TC-015-05: Deterministic quorum summary
115+
**File**: `internal/dun/quorum_test.go`
116+
**Priority**: P1
117+
**Covers**: AC-5
118+
119+
```go
120+
func TestQuorumSummaryDeterministic(t *testing.T) {
121+
// Given: stable inputs
122+
// Then: summary fields are ordered and deterministic
123+
}
124+
```
125+
126+
### 5.5 Loop Integration
127+
128+
#### TC-015-06: Loop uses shared quorum engine
129+
**File**: `cmd/dun/main_test.go`
130+
**Priority**: P1
131+
**Covers**: AC-6
132+
133+
```go
134+
func TestLoopUsesSharedQuorumEngine(t *testing.T) {
135+
// Given: loop with --quorum
136+
// Then: shared quorum engine is invoked
137+
}
138+
```

‎docs/helix/04-build/implementation-plans/IP-015-agent-quorum.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ dun:
77
- F-018
88
- US-011
99
- TP-011
10+
- TP-015
1011
- helix.prd
1112
review:
1213
self_hash: ''
@@ -28,6 +29,7 @@ dun:
2829
- F-018 Agent Quorum (`docs/helix/01-frame/features/F-018-agent-quorum.md`)
2930
- US-011 Agent Quorum (`docs/helix/01-frame/user-stories/US-011-agent-quorum.md`)
3031
- TP-011 Agent Quorum Test Plan (`docs/helix/03-test/test-plans/TP-011-agent-quorum.md`)
32+
- TP-015 Agent Quorum + Synthesis Implementation Plan (`docs/helix/03-test/test-plans/TP-015-agent-quorum-implementation.md`)
3133
- SD-011 Agent Quorum Solution Design (`docs/helix/02-design/solution-designs/SD-011-agent-quorum.md`)
3234
- TD-011 Agent Quorum Technical Design (`docs/helix/02-design/technical-designs/TD-011-agent-quorum.md`)
3335

0 commit comments

Comments
 (0)