self-evolving-workflow 0.0.0-stage → 0.1.3
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/LICENSE +27 -0
- package/README.md +90 -2
- package/dist/agent-memory-prompts.d.ts +13 -0
- package/dist/agent-memory-prompts.js +55 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +6 -0
- package/dist/closeout.d.ts +105 -0
- package/dist/closeout.js +479 -0
- package/dist/code.d.ts +39 -0
- package/dist/code.js +124 -0
- package/dist/common.d.ts +9 -0
- package/dist/common.js +42 -0
- package/dist/context-envelope.d.ts +59 -0
- package/dist/context-envelope.js +23 -0
- package/dist/host-adapters.d.ts +34 -0
- package/dist/host-adapters.js +151 -0
- package/dist/http.d.ts +3 -0
- package/dist/http.js +90 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +13 -0
- package/dist/knowledge-cli.d.ts +183 -0
- package/dist/knowledge-cli.js +654 -0
- package/dist/knowledge-reads.d.ts +71 -0
- package/dist/knowledge-reads.js +193 -0
- package/dist/memory.d.ts +97 -0
- package/dist/memory.js +250 -0
- package/dist/retrospective.d.ts +57 -0
- package/dist/retrospective.js +248 -0
- package/dist/search.d.ts +36 -0
- package/dist/search.js +112 -0
- package/dist/skill-addition.d.ts +25 -0
- package/dist/skill-addition.js +89 -0
- package/dist/skill-design.d.ts +96 -0
- package/dist/skill-design.js +226 -0
- package/dist/skill-replay.d.ts +55 -0
- package/dist/skill-replay.js +451 -0
- package/dist/skill-route.d.ts +30 -0
- package/dist/skill-route.js +75 -0
- package/dist/transcript-evidence.d.ts +3 -0
- package/dist/transcript-evidence.js +58 -0
- package/dist/upstream/chunker.d.ts +24 -0
- package/dist/upstream/chunker.js +96 -0
- package/dist/upstream/file-protocol.d.ts +45 -0
- package/dist/upstream/file-protocol.js +117 -0
- package/dist/upstream/frontmatter.d.ts +47 -0
- package/dist/upstream/frontmatter.js +86 -0
- package/dist/upstream/graph-search.d.ts +33 -0
- package/dist/upstream/graph-search.js +67 -0
- package/dist/upstream/l1-extraction.d.ts +26 -0
- package/dist/upstream/l1-extraction.js +405 -0
- package/dist/upstream/llm.d.ts +8 -0
- package/dist/upstream/llm.js +1 -0
- package/dist/upstream/merge.d.ts +50 -0
- package/dist/upstream/merge.js +153 -0
- package/dist/upstream/prompts.d.ts +53 -0
- package/dist/upstream/prompts.js +185 -0
- package/dist/upstream/search-utils.d.ts +34 -0
- package/dist/upstream/search-utils.js +55 -0
- package/dist/upstream/slug.d.ts +26 -0
- package/dist/upstream/slug.js +103 -0
- package/dist/upstream/template.d.ts +29 -0
- package/dist/upstream/template.js +80 -0
- package/dist/upstream/tokenize.d.ts +4 -0
- package/dist/upstream/tokenize.js +29 -0
- package/dist/wiki-change.d.ts +76 -0
- package/dist/wiki-change.js +299 -0
- package/dist/wiki-entry.d.ts +26 -0
- package/dist/wiki-entry.js +93 -0
- package/dist/wiki-ingest.d.ts +12 -0
- package/dist/wiki-ingest.js +126 -0
- package/dist/wiki-migration.d.ts +16 -0
- package/dist/wiki-migration.js +268 -0
- package/dist/wiki-tokens.d.ts +1 -0
- package/dist/wiki-tokens.js +46 -0
- package/dist/wiki.d.ts +103 -0
- package/dist/wiki.js +330 -0
- package/dist/workflow-cli.d.ts +2 -0
- package/dist/workflow-cli.js +258 -0
- package/dist/workflow-install.d.ts +36 -0
- package/dist/workflow-install.js +148 -0
- package/dist/workflow-knowledge.d.ts +16 -0
- package/dist/workflow-knowledge.js +24 -0
- package/dist/workflow-mcp.d.ts +2 -0
- package/dist/workflow-mcp.js +144 -0
- package/dist/workflow-names.d.ts +4 -0
- package/dist/workflow-names.js +18 -0
- package/dist/workflow-runtime.d.ts +622 -0
- package/dist/workflow-runtime.js +627 -0
- package/dist/workflow-skills.d.ts +48 -0
- package/dist/workflow-skills.js +141 -0
- package/package.json +76 -4
- package/skills/ew-odyssey/SKILL.md +237 -0
- package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
- package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
- package/skills/ew-odyssey/references/odyssey-base.md +278 -0
- package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
- package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
- package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
- package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
- package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
- package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
- package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
- package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
- package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
- package/skills/ew-odyssey/references/odyssey-review.md +251 -0
- package/skills/ew-odyssey/references/odyssey-security.md +249 -0
- package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
- package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
- package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
- package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
- package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
- package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
- package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
- package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
- package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
- package/skills/ew-orchestrate/SKILL.md +236 -0
- package/skills/ew-orchestrate/references/auto-policy.md +165 -0
- package/skills/ew-orchestrate/references/companion-route.md +52 -0
- package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
- package/skills/ew-orchestrate/references/goal.md +53 -0
- package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
- package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
- package/skills/ew-orchestrate/references/planning.md +137 -0
- package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
- package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
- package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
- package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
- package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
- package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
- package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
- package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
- package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
- package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
- package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
- package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
- package/skills/ew-skill-design/SKILL.md +28 -0
- package/skills/ew-skill-design/references/package-contract.md +28 -0
- package/skills/ew-skill-design/references/validation.md +7 -0
- package/skills/team-swarm/SKILL.md +231 -0
- package/skills/team-swarm/references/mcp-coordination.md +10 -0
- package/skills/team-swarm/roles/analyst/role.md +181 -0
- package/skills/team-swarm/roles/ant/role.md +149 -0
- package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
- package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
- package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
- package/skills/team-swarm/roles/coordinator/role.md +228 -0
- package/skills/team-swarm/roles/scorer/role.md +150 -0
- package/skills/team-swarm/scripts/aco.py +646 -0
- package/skills/team-swarm/scripts/pheromone.py +144 -0
- package/skills/team-swarm/scripts/scoring.py +111 -0
- package/skills/team-swarm/scripts/test_aco.py +606 -0
- package/skills/team-swarm/specs/ant-output-schema.md +127 -0
- package/skills/team-swarm/specs/convergence-criteria.md +108 -0
- package/skills/team-swarm/specs/pheromone-schema.md +125 -0
- package/skills/team-swarm/specs/swarm-config-template.json +71 -0
- package/skills/team-swarm/specs/swarm-protocol.md +123 -0
- package/skills/workflow-closeout/SKILL.md +10 -0
- package/skills/workflow-evolve/SKILL.md +79 -0
- package/skills/workflow-evolve/references/agy-gate.md +27 -0
- package/skills/workflow-evolve/references/auto-loop.md +20 -0
- package/skills/workflow-evolve/references/history-review.md +14 -0
- package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
- package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
- package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
- package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
- package/workflows/index.json +23 -0
|
@@ -0,0 +1,373 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-execute
|
|
3
|
+
prepare: execute
|
|
4
|
+
commands: [ew-execute]
|
|
5
|
+
session-mode: inherited
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Workflow: Execute
|
|
9
|
+
|
|
10
|
+
Wave-based parallel execution — atomic commits, checkpoint resume, built-in smoke self-check. Artifacts unified as `execution.json`; implementation scope and evidence handed to verify.
|
|
11
|
+
|
|
12
|
+
## Iron Law
|
|
13
|
+
|
|
14
|
+
Never mark a task `completed` without running its convergence criteria. Every completion requires:
|
|
15
|
+
|
|
16
|
+
1. Run the convergence criteria check
|
|
17
|
+
2. Confirm output matches the task definition
|
|
18
|
+
3. Have a re-computable verification record in the task evidence
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## Step 0: Plan availability & degradation routing
|
|
23
|
+
|
|
24
|
+
Resolve `current-plan` through the Run packet's `upstream_aliases` and read its `upstream` path relative to the Session directory. In a legacy Run, use its existing upstream data.
|
|
25
|
+
|
|
26
|
+
**Plan present** → proceed to Step 1 (parse execution options).
|
|
27
|
+
|
|
28
|
+
**Plan absent** → degradation mode. Inspect available upstream artifacts:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
IF latest-review (review-findings) is available:
|
|
32
|
+
count findings with actionable fix scope
|
|
33
|
+
IF ≤3 findings AND each touches ≤2 files:
|
|
34
|
+
→ Companion path: write report.md with degradation note,
|
|
35
|
+
run `evolve run cancel {run_id} --session {session_id} --actor {actor_id} --expected-run-revision {run_revision} --expected-orchestration-revision {orchestration_revision} --json`,
|
|
36
|
+
then surface the finding summaries to Evolve's internal Companion route
|
|
37
|
+
ELSE:
|
|
38
|
+
→ Odyssey planex path: write report.md with degradation note,
|
|
39
|
+
run `evolve run cancel {run_id} --session {session_id} --actor {actor_id} --expected-run-revision {run_revision} --expected-orchestration-revision {orchestration_revision} --json`,
|
|
40
|
+
then surface: /odyssey-planex "<review findings as requirement>"
|
|
41
|
+
|
|
42
|
+
ELSE IF latest-debug (diagnosis) is available AND fix-directions present:
|
|
43
|
+
IF fix scope ≤2 files:
|
|
44
|
+
→ Companion path (same cancellation and reroute protocol as above)
|
|
45
|
+
ELSE:
|
|
46
|
+
→ Odyssey planex path (same cancellation and reroute protocol as above)
|
|
47
|
+
|
|
48
|
+
ELSE:
|
|
49
|
+
→ E001: No plan and no alternative upstream. Abort.
|
|
50
|
+
Write report.md with verdict: blocked, summary: "No current-plan; run plan first"
|
|
51
|
+
run `evolve run transition {run_id} blocked --session {session_id} --actor {actor_id} --expected-run-revision {run_revision} --json`
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
**Degradation transition protocol**: cancellation or blocked transition preserves the attempted Run without claiming completion. Each mutation uses the exact Run revision from the latest birth/check receipt, and the explicit Session locator. A cancelled/failed attempt leaves its chain step pending; do not allocate a retry implicitly. report.md MUST note: (1) why degradation was triggered, (2) which upstream was available, (3) the target command. The `next` field in report frontmatter points to the degradation target.
|
|
55
|
+
|
|
56
|
+
**Never proceed to Step 1+ without a plan.** The execution machinery below requires a normalized in-memory execution model. A structured Evolve plan supplies it directly; a `plan/1.0` artifact with `source_format: pi-markdown` must first be normalized from its authoritative Markdown as specified in Step 2.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Step 1: Parse execution options
|
|
61
|
+
|
|
62
|
+
With `-y`, use the parsed defaults and skip all interactive questions (throughout the entire execution, not just this step); also skip when the plan already carries executionMethod.
|
|
63
|
+
|
|
64
|
+
Otherwise build the option prompts from the enabled tools:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
available tools = enabled tools from the Codex or Agy executables available to the host (excluding agent, which is always available)
|
|
68
|
+
frontendTool = first tool with the "frontend" tag, fall back to first enabled
|
|
69
|
+
backendTool = first tool with the "backend" tag, fall back to first enabled
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
| Question | Resolution |
|
|
73
|
+
|------|------|
|
|
74
|
+
| Executor (how to execute tasks) | Auto → `domainRouting {frontend, backend, default:"agent"}`; tool name → single executor; Other text → parse by domain rules (e.g. `frontend gemini backend codex`) |
|
|
75
|
+
| Review (code-review after execution?) | store as `codeReviewTool`, Skip means no review |
|
|
76
|
+
| Verify (smoke self-check tool?) | Auto → first enabled; tool name → that tool; Skip → do nothing |
|
|
77
|
+
|
|
78
|
+
Store `executionMethod`, `domainRouting`, `codeReviewTool`, `verificationTool`.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Step 2: Load plan
|
|
83
|
+
|
|
84
|
+
Read the plan from the `current-plan` path resolved in Step 0.
|
|
85
|
+
|
|
86
|
+
Normalize it before any checkpoint or wave logic:
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
IF plan.source_format == "pi-markdown":
|
|
90
|
+
authoritativeBody = plan.markdown
|
|
91
|
+
derive objective from the title/goal
|
|
92
|
+
derive tasks from explicit ordered items, checklists, scoped headings, and implementation steps
|
|
93
|
+
preserve explicit dependencies; otherwise keep the declared order
|
|
94
|
+
derive convergence criteria from acceptance/verification/success sections and task-local checks
|
|
95
|
+
if no task split is explicit, create one task covering the complete Markdown body
|
|
96
|
+
topologically group non-conflicting tasks into in-memory waves
|
|
97
|
+
normalizedPlan = { objective, tasks, waves, constraints, acceptance_criteria, source:"pi-markdown" }
|
|
98
|
+
# The artifact has no persisted task status. Resume only from this Run's execution/checkpoint artifacts.
|
|
99
|
+
ELSE:
|
|
100
|
+
normalizedPlan = the structured Evolve plan
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
The derived model is an execution projection only. Do not write it back over `current-plan`, drop prose requirements, invent extra scope, or require absent `task_ids`/`wave_ids`.
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
executionMethod = Step 1 choice || --method || normalizedPlan default || "auto"
|
|
107
|
+
defaultExecutor = --executor || first enabled tool
|
|
108
|
+
domainRouting = Step 1 || build from delegate-config domain tags (frontend/backend match tag, default "agent")
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
**Checkpoint resume**: for a structured plan, scan persisted task statuses. For `pi-markdown`, scan `current-execution` and this Run's checkpoint/task summaries keyed by the derived task IDs. Collect completed tasks and resume at the first wave containing an incomplete task.
|
|
112
|
+
|
|
113
|
+
**Build wave queue**: build from `normalizedPlan.waves`, keeping only waves that contain incomplete tasks. Every later reference to `task`, `wave`, convergence criteria, or plan scope uses `normalizedPlan`.
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Step 3: Load project rules
|
|
118
|
+
|
|
119
|
+
Reuse the bound `session-priors` for covered Wiki scope. Use `wiki_context` for additional paths or coding and UI categories required by the implementation.
|
|
120
|
+
|
|
121
|
+
Pass task rules to each executor in Step 4. The current package does not maintain a second Spec loader.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Step 4: Wave parallel execution
|
|
126
|
+
|
|
127
|
+
### Executor resolution
|
|
128
|
+
|
|
129
|
+
Priority: per-task explicit assignment > explicit method > auto domain routing.
|
|
130
|
+
|
|
131
|
+
- **Single mode** (method is agent/cli/a specific tool): all tasks use that executor.
|
|
132
|
+
- **auto mode**: determine domain per task, look up `domainRouting[domain]`, fall back to `domainRouting.default`.
|
|
133
|
+
|
|
134
|
+
Determine domain from the task definition (scope, file paths, action):
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
frontend — UI component/page/style/layout (.tsx/.jsx/.vue/.css/.html, scope contains ui/component/style/page/view)
|
|
138
|
+
backend — API/server/database/service/algorithm (.go/.rs/.java/.py/.sql/.proto, scope contains api/server/database/service/worker)
|
|
139
|
+
general — mixed, only .ts/.js, config, tests, or domain unclear
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Record the routing decision per task before dispatch: `TASK-001 [frontend] → gemini`.
|
|
143
|
+
|
|
144
|
+
### Delegate writing skeleton
|
|
145
|
+
|
|
146
|
+
The CLI backend (evolve delegate) and the agent path build the prompt from the same task information:
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
PURPOSE: implement ${task.id}: ${task.title}; success = all convergence criteria pass
|
|
150
|
+
TASK: ${task.action} | read existing code first | after changes, verify each convergence criterion
|
|
151
|
+
MODE: write
|
|
152
|
+
CONTEXT: @${task.scope}/**/* | Session goal: ${session.goal}
|
|
153
|
+
EXPECTED: runnable code changes + all criteria verified + summary of work done
|
|
154
|
+
CONSTRAINTS: scope limited to task files | follow project specs
|
|
155
|
+
|
|
156
|
+
## Task definition
|
|
157
|
+
Scope / Action / Files (path→target: change) / Read First / Implementation steps / Convergence Criteria / Reference
|
|
158
|
+
## Session context (goal + success criteria)
|
|
159
|
+
## Project specs (specs_content)
|
|
160
|
+
## Prior task summaries (prior summaries)
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
### Execution loop
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
for each wave in queue (serial):
|
|
167
|
+
on the first wave, if report status is not marked executing, mark it
|
|
168
|
+
|
|
169
|
+
for each task in wave.tasks (parallel):
|
|
170
|
+
load task definition; resolve executor
|
|
171
|
+
|
|
172
|
+
IF executor == "agent":
|
|
173
|
+
dispatch workflow-executor agent (fresh 200k context):
|
|
174
|
+
task definition, session context, prior wave summaries, specs_content
|
|
175
|
+
the agent runs the full lifecycle internally:
|
|
176
|
+
implement → verify convergence → auto-fix (up to 3) → commit
|
|
177
|
+
→ write {run_dir}/outputs/summaries/${task.id}.md → update task status (checkpoint if blocked)
|
|
178
|
+
the main flow verifies the agent wrote a summary + updated status, collects the result
|
|
179
|
+
|
|
180
|
+
ELSE (CLI path evolve delegate):
|
|
181
|
+
fixedId = "${scope_slug}-${task.id}", stored in the execution record
|
|
182
|
+
dispatch: evolve delegate "${prompt}" --to ${executor} --mode write --id ${fixedId}
|
|
183
|
+
after dispatch the main flow verifies convergence criteria against file state
|
|
184
|
+
the main flow writes the summary, updates task status, auto-commits if enabled
|
|
185
|
+
|
|
186
|
+
collect result: { task.id, status, executor, summary_path, commit_hash, delegate_id }
|
|
187
|
+
|
|
188
|
+
wait for all tasks in the wave to complete
|
|
189
|
+
IF any blocked AND not -y: ask the user to continue/stop
|
|
190
|
+
ELSE: automatically proceed to the next wave (never ask between waves)
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Parallel dispatch rules
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
Dispatch all tasks in a wave in parallel in a single message (agent + CLI mixed).
|
|
197
|
+
agent tasks: run_in_background false | CLI tasks: run_in_background true
|
|
198
|
+
one independent dispatch per task, never merge multiple tasks into one delegate prompt
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Failure handling
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
Up to 3 auto-fixes per task:
|
|
205
|
+
agent path: handled internally by workflow-executor
|
|
206
|
+
CLI path: 1) --resume ${fixedId} → 2) simplify prompt → 3) fall back to agent, mark [LOW CONFIDENCE]
|
|
207
|
+
|
|
208
|
+
All 3 fail: mark "blocked" and write a checkpoint { attempt:3, last_error, partial_files, executor, delegate_id }
|
|
209
|
+
continue the current wave (other tasks unaffected)
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Step 5: Post-wave validation
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
Check 1 summary exists: completed task missing summary → warning "missing_summary"
|
|
218
|
+
Check 2 status consistency: cross-check task status against wave_results → mismatch (missing side is critical)
|
|
219
|
+
Check 3 tech stack constraints: extract allowed_languages/disallowed_imports/required_patterns from specs,
|
|
220
|
+
scan the files changed by completed tasks, hit on disallowed → critical "tech_stack_violation"
|
|
221
|
+
Check 4 CLI supplementary validation (optional, skip if no CLI tool or no completed tasks):
|
|
222
|
+
evolve delegate analysis mode scans changed files for circular deps / dead code / breaking changes,
|
|
223
|
+
critical items merged into violations
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
**Gate logic**: any critical → mark blocked, record blocked_reason + violations, abort; no critical → continue.
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## Step 6: Code review (optional)
|
|
231
|
+
|
|
232
|
+
If `codeReviewTool == "Skip"` skip. Otherwise evolve delegate (run_in_background) reviews the git diff (execution start point → HEAD) for correctness/style/bugs, record the findings summary.
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## Step 7: Smoke Self-Check
|
|
237
|
+
|
|
238
|
+
If `verificationTool == "Skip"` or there are no completed tasks, skip. **This is only a smoke check, not an acceptance verdict** — formal acceptance is in a separate verify run.
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
1. Collect files changed by completed tasks, each task's convergence.criteria, session success criteria
|
|
242
|
+
2. Resolve tool: Auto → first enabled, otherwise the specified tool
|
|
243
|
+
3. Dispatch evolve delegate (analysis mode) to do one smoke pass:
|
|
244
|
+
- CONVERGENCE: verify each criterion against the code, with file:line evidence
|
|
245
|
+
- Existence: expected output files exist on disk
|
|
246
|
+
- Substance: files have real implementation, not stub/placeholder/TODO-only/empty return
|
|
247
|
+
- Wiring: files are imported and used by the system, not orphaned
|
|
248
|
+
- Anti-patterns: scan for TODO/FIXME/HACK, placeholder, debug print, disabled tests
|
|
249
|
+
4. Write outputs/self-check.json: # GATE: self-check-passed (smoke executed + no unhandled critical violation, see Step 5 Check 3; gaps_found does NOT block)
|
|
250
|
+
{ checks:[{criterion, status:"verified"|"failed"|"uncertain", evidence}],
|
|
251
|
+
structure:{existence[], substance[], wiring[]}, anti_patterns[],
|
|
252
|
+
overall:"passed"|"gaps_found" }
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
The self-check only records the smoke conclusion as supporting evidence for verify, and never issues the final acceptance based on it. gaps_found does not block execute completion, but must be noted as concerns in the report for verify to consume.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Step 8: Write artifacts
|
|
260
|
+
|
|
261
|
+
```
|
|
262
|
+
outputs/execution.json:
|
|
263
|
+
{ "plan_ref":"current-plan", "status":"completed|partial|blocked",
|
|
264
|
+
"waves":[...], "completed_tasks":[...], "blocked_tasks":[...] }
|
|
265
|
+
|
|
266
|
+
outputs/task-results.json:
|
|
267
|
+
per-task executor, attempt, files changed, commands/tests, criterion evidence, status
|
|
268
|
+
|
|
269
|
+
outputs/change-manifest.json:
|
|
270
|
+
repo-relative file paths, change type (create/modify/delete), task refs
|
|
271
|
+
|
|
272
|
+
outputs/self-check.json (Step 7)
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## Step 9: Extract incremental learnings
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
Read all outputs/summaries/*.md, extract strategy adjustments, patterns, pitfalls.
|
|
281
|
+
Deduplicate against the rules resolved in Step 3.
|
|
282
|
+
Stage reusable learnings through the unified Agent Memory Wiki proposal route after the Run is sealed. Never write Wiki files directly from routine Run completion.
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
Full knowledge extraction (constraints → spec, decisions → knowhow, terminology → domain glossary) is not done here; it is handled uniformly at session wrap-up.
|
|
286
|
+
|
|
287
|
+
→ Wrap-up follows ref/finish-work.md (stages knowledge candidates BEFORE seal; corpus writes only via post-seal promote)
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## report.md
|
|
292
|
+
|
|
293
|
+
Write `report.md` with standard frontmatter + fixed sections. frontmatter verdict mapping:
|
|
294
|
+
|
|
295
|
+
| Situation | verdict |
|
|
296
|
+
|------|---------|
|
|
297
|
+
| all tasks succeeded | ready |
|
|
298
|
+
| some non-critical blocked | ready_with_concerns |
|
|
299
|
+
| critical dependency failed | blocked |
|
|
300
|
+
| execution itself errored (no outputs) | failed |
|
|
301
|
+
|
|
302
|
+
next explicitly routes to a separate verify:
|
|
303
|
+
|
|
304
|
+
```yaml
|
|
305
|
+
next:
|
|
306
|
+
- { command: verify, reason: implementation complete, needs: [current-plan, current-execution] }
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Body contains an execution status summary (completed/failed task counts, blocked reasons) and handoff.
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
313
|
+
## GateRecord
|
|
314
|
+
|
|
315
|
+
After execution completes, inline-record one entry per declared gate. **GATE: execution-complete**
|
|
316
|
+
|
|
317
|
+
```json
|
|
318
|
+
{ "gate": "execution-complete", "verdict": "ready|ready_with_concerns|blocked|failed", "checked_at": now(),
|
|
319
|
+
"evidence": { "completed": N, "blocked": N },
|
|
320
|
+
"artifact": "outputs/execution.json" }
|
|
321
|
+
{ "gate": "self-check-passed", "verdict": "ready|ready_with_concerns|blocked|failed", "checked_at": now(),
|
|
322
|
+
"evidence": { "smoke_ran": true, "self_check": "passed|gaps_found", "critical_violations": N },
|
|
323
|
+
"artifact": "outputs/self-check.json" }
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
BLOCKED conditions: `execution.json` missing, or there are completed tasks but missing summary/status not updated, or Step 5 has an unhandled critical violation.
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
## Success Criteria
|
|
331
|
+
|
|
332
|
+
- [ ] Execution method selected (agent/cli/auto)
|
|
333
|
+
- [ ] All tasks in plan reached terminal state (done/blocked)
|
|
334
|
+
- [ ] Each completed task has summary, evidence, and status
|
|
335
|
+
- [ ] Atomic commits produced per task (only task's changed files)
|
|
336
|
+
- [ ] Self-check smoke (build/test) executed and recorded (gaps_found recorded as concerns for verify)
|
|
337
|
+
- [ ] No unhandled tech-stack violations
|
|
338
|
+
- [ ] execution.json written with completion status
|
|
339
|
+
- [ ] Blocked tasks have checkpoint for resume
|
|
340
|
+
|
|
341
|
+
---
|
|
342
|
+
|
|
343
|
+
## Checkpoint resume
|
|
344
|
+
|
|
345
|
+
```
|
|
346
|
+
State recorded in the execution record: completed tasks, current_wave, commits, method,
|
|
347
|
+
default_executor, delegate_ids{ task.id: fixedId }
|
|
348
|
+
|
|
349
|
+
Resume behavior:
|
|
350
|
+
check each task's status + the delegate status of in-progress CLI tasks
|
|
351
|
+
CLI tasks: take completed output, or --resume ${fixedId} to retry
|
|
352
|
+
build the remaining task queue, continue from the next incomplete wave, do not re-run completed tasks
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
357
|
+
---
|
|
358
|
+
|
|
359
|
+
## Error Codes
|
|
360
|
+
|
|
361
|
+
| Code | Condition | Recovery |
|
|
362
|
+
|------|-----------|----------|
|
|
363
|
+
| E001 | No plan and no alternative upstream | Abort: `current-plan` missing and no review-findings/fix-directions/diagnosis available. Run plan first, or provide review/debug upstream for degradation routing |
|
|
364
|
+
| E002 | Entire wave all blocked | Stop execution, report the blocked wave; downstream tasks with unmet dependencies marked upstream_blocked |
|
|
365
|
+
| W001 | Task file missing | Skip that task, record error, continue the current wave |
|
|
366
|
+
| W002 | Agent dispatch failed | Retry once, mark blocked if still failing |
|
|
367
|
+
| W003 | Delegate failed | `--resume ${fixedId}` → fall back to agent, mark [LOW CONFIDENCE] |
|
|
368
|
+
| W004 | Git commit failed | Record warning, mark [LOW CONFIDENCE] (commit failed), don't mark fully complete until commit succeeds |
|
|
369
|
+
|
|
370
|
+
## Knowledge Hooks
|
|
371
|
+
|
|
372
|
+
- `--trace` records consumed IDs in `knowledge_reads`; exact reads use `agent-memory wiki reference <id>` or `agent-memory memory get <id>`.
|
|
373
|
+
- Stage reusable recipes and pitfalls through `agent-memory wiki propose`; never write Wiki files directly.
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-plan
|
|
3
|
+
wiki_categories: [arch]
|
|
4
|
+
search_profile:
|
|
5
|
+
wiki: [constraints, references]
|
|
6
|
+
memory: [work_method, error, retry]
|
|
7
|
+
description: Decompose confirmed analysis or requirements into an executable DAG, waves, and collision-free tasks
|
|
8
|
+
argument-hint: '[scope] [--gaps] [--tdd] [--revise [instructions]] [--check <plan-dir>] [-y]'
|
|
9
|
+
contract:
|
|
10
|
+
consumes:
|
|
11
|
+
- kind: findings
|
|
12
|
+
alias: current-analysis
|
|
13
|
+
required: false
|
|
14
|
+
schema: findings/1.0
|
|
15
|
+
role: primary
|
|
16
|
+
- kind: diagnosis
|
|
17
|
+
alias: latest-debug
|
|
18
|
+
required: false
|
|
19
|
+
schema: diagnosis/1.0
|
|
20
|
+
role: primary
|
|
21
|
+
- kind: review-findings
|
|
22
|
+
alias: latest-review
|
|
23
|
+
required: false
|
|
24
|
+
schema: review-findings/1.0
|
|
25
|
+
role: primary
|
|
26
|
+
accepts_negative_evidence: true
|
|
27
|
+
- kind: verification
|
|
28
|
+
alias: latest-verification
|
|
29
|
+
required: false
|
|
30
|
+
schema: verification/1.0
|
|
31
|
+
role: primary
|
|
32
|
+
accepts_negative_evidence: true
|
|
33
|
+
- kind: blueprint
|
|
34
|
+
alias: current-blueprint
|
|
35
|
+
required: false
|
|
36
|
+
schema: blueprint/1.0
|
|
37
|
+
role: primary
|
|
38
|
+
- kind: roadmap
|
|
39
|
+
alias: current-roadmap
|
|
40
|
+
required: false
|
|
41
|
+
schema: roadmap/1.0
|
|
42
|
+
role: primary
|
|
43
|
+
- kind: plan
|
|
44
|
+
required: false
|
|
45
|
+
schema: plan/1.0
|
|
46
|
+
role: primary
|
|
47
|
+
- kind: priors
|
|
48
|
+
alias: session-priors
|
|
49
|
+
required: false
|
|
50
|
+
schema: priors/1.0
|
|
51
|
+
role: evidence
|
|
52
|
+
produces:
|
|
53
|
+
- path: outputs/plan.json
|
|
54
|
+
kind: plan
|
|
55
|
+
alias: current-plan
|
|
56
|
+
role: primary
|
|
57
|
+
required: true
|
|
58
|
+
schema: plan/1.0
|
|
59
|
+
- path: outputs/tasks/TASK-{NNN}.json
|
|
60
|
+
kind: plan-task
|
|
61
|
+
role: attachment
|
|
62
|
+
required: false
|
|
63
|
+
schema: plan-task/1.0
|
|
64
|
+
- path: outputs/waves.json
|
|
65
|
+
kind: execution-waves
|
|
66
|
+
role: attachment
|
|
67
|
+
required: false
|
|
68
|
+
schema: execution-waves/1.0
|
|
69
|
+
- path: outputs/dependency-graph.json
|
|
70
|
+
kind: dependency-graph
|
|
71
|
+
role: evidence
|
|
72
|
+
required: false
|
|
73
|
+
schema: dependency-graph/1.0
|
|
74
|
+
- path: outputs/collision-report.json
|
|
75
|
+
kind: collision-report
|
|
76
|
+
role: evidence
|
|
77
|
+
required: false
|
|
78
|
+
schema: collision-report/1.0
|
|
79
|
+
- path: outputs/plan-check.json
|
|
80
|
+
kind: plan-check
|
|
81
|
+
role: evidence
|
|
82
|
+
required: false
|
|
83
|
+
schema: plan-check/1.0
|
|
84
|
+
gates:
|
|
85
|
+
exit:
|
|
86
|
+
- context-collected
|
|
87
|
+
- plan-generated
|
|
88
|
+
- plan-checked
|
|
89
|
+
- plan-confirmed
|
|
90
|
+
contract_version: 2.1
|
|
91
|
+
required_links:
|
|
92
|
+
- references/prepare.md
|
|
93
|
+
- references/workflow.md
|
|
94
|
+
session-mode: run
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
# Plan
|
|
98
|
+
|
|
99
|
+
Read [preparation](references/prepare.md), then follow the [workflow](references/workflow.md).
|
|
100
|
+
|
|
101
|
+
- Read [boundary review](references/boundary-grill.md) when task boundaries or file writes conflict.
|
|
102
|
+
- Read [test-first planning](references/tdd.md) when invoked with `--tdd`.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Boundary Grill — Embedded Mini-Review Protocol
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
## Conflict Types
|
|
5
|
+
|
|
6
|
+
| ID | Signal | Example |
|
|
7
|
+
|----|--------|---------|
|
|
8
|
+
| `RSC` | Decision outside command's scope guard | analyze outputs task-level details (plan scope) |
|
|
9
|
+
| `MOD` | Changes cross 2+ module boundaries | task touches `commands/` and `hooks/` without declaring cross-module |
|
|
10
|
+
| `DEC` | Upstream locked decision contradicts code | locked "use EventEmitter" but code uses Subject at `file:line` |
|
|
11
|
+
|
|
12
|
+
## Trigger
|
|
13
|
+
|
|
14
|
+
Run boundary grill when ANY of:
|
|
15
|
+
- **RSC**: produced decision matches another command's scope guard keywords
|
|
16
|
+
- **MOD**: `ARCHITECTURE.md` exists AND changes touch 2+ top-level modules
|
|
17
|
+
- **DEC**: upstream Locked decisions AND code grep shows contradicting patterns
|
|
18
|
+
|
|
19
|
+
Priority when >3 conflicts: DEC > RSC > MOD.
|
|
20
|
+
|
|
21
|
+
## Protocol
|
|
22
|
+
|
|
23
|
+
Per conflict (max 3 conflicts × 3 questions = 9 total):
|
|
24
|
+
1. State the conflict with `file:line` evidence
|
|
25
|
+
2. Ask 2-3 adversarial questions via AskUserQuestion — challenge with code reality
|
|
26
|
+
3. Resolve: RESOLVED (evidence-based) / DEFERRED (needs escalation) / ACCEPTED_RISK
|
|
27
|
+
|
|
28
|
+
**Auto mode (`-y`)**: skip questions, resolve via code evidence weighting:
|
|
29
|
+
- RSC → defer to target scope
|
|
30
|
+
- MOD → follow existing cross-module pattern (or flag as risk)
|
|
31
|
+
- DEC → code wins (current code = ground truth)
|
|
32
|
+
|
|
33
|
+
## Output
|
|
34
|
+
|
|
35
|
+
Append to calling command's primary output:
|
|
36
|
+
|
|
37
|
+
```markdown
|
|
38
|
+
## Boundary Grill Results
|
|
39
|
+
|
|
40
|
+
| # | Type | Conflict | Resolution | Evidence |
|
|
41
|
+
|---|------|----------|------------|----------|
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Feed into `context.md`: resolved DEC → amend Locked; unresolved → Deferred with `boundary_grill: true`.
|
|
45
|
+
|
|
46
|
+
## Constraints
|
|
47
|
+
|
|
48
|
+
- Non-blocking — warnings + resolutions, never hard stops
|
|
49
|
+
- Evidence MUST include `file:line` — generic assertions invalid
|
|
50
|
+
- Results visible in command output — no silent swallowing
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
refs:
|
|
3
|
+
- path: ref/boundary-grill.md
|
|
4
|
+
when: Task boundary or file write conflict
|
|
5
|
+
- path: ref/tdd.md
|
|
6
|
+
when: --tdd mode
|
|
7
|
+
- path: ref/finish-work.md
|
|
8
|
+
when: Wrapping up
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Pre-task Thinking: plan
|
|
12
|
+
|
|
13
|
+
## Purpose
|
|
14
|
+
|
|
15
|
+
The output of plan is "task JSON an executor can follow to finish the work," not a task-list overview. Understand the input and boundaries before you start.
|
|
16
|
+
|
|
17
|
+
## Input Interpretation
|
|
18
|
+
|
|
19
|
+
- Resolve input aliases through the Run packet's `upstream_aliases` and read the corresponding Artifact paths in `upstream` relative to the Session directory. `current-analysis` takes priority. `--gaps` consumes registered issues plus available `latest-review`, `latest-verification`, and `latest-debug` evidence. If there is no usable source, report E001. In a legacy Run, use its existing upstream data.
|
|
20
|
+
- How large is the scope? It determines single-agent vs 2+1 agent mode: ≤3 modules single agent (≤8 tasks); >3 modules 2+1 (2 parallel planners of ≤8 each + 1 synthesis agent, total ≤16). Module count is derived from milestone phase definitions and the analyze upstream.
|
|
21
|
+
- Is it a special mode? `--revise` loads an existing plan for incremental changes (skips preceding phases); `--check` is read-only validation; `--tdd` generates a test-first task chain (open [test-first planning](tdd.md)). All three bypass the standard create pipeline.
|
|
22
|
+
|
|
23
|
+
## Required Context
|
|
24
|
+
|
|
25
|
+
- Open bound `session-priors` and reuse its Wiki bodies for the same lookup scope. Query through Run MCP when the plan adds a task, path, category or repository scope.
|
|
26
|
+
- With `current-analysis`: read `findings.json#decisions` — locked as inviolable constraints, free left to the implementer's discretion, deferred explicitly excluded; `findings[]` and recommendation as task-scope input. If upstream gave implementation_scope, 1 scope item → 1 task.
|
|
27
|
+
- With `latest-review`/`latest-debug` (`--gaps`): preserve review finding IDs and severity, cluster shared root causes, and produce traceable fix tasks; issue-backed gaps keep bidirectional `issue_id` links.
|
|
28
|
+
- Pass the Run's `wiki_constraints` to the planner when the field is present. An empty list is a resolved result. Follow the workflow's legacy rules lookup when the field is absent.
|
|
29
|
+
|
|
30
|
+
## Boundaries and Invariants
|
|
31
|
+
|
|
32
|
+
- One feature = one task (even if it touches 3-5 files); never split by file.
|
|
33
|
+
- Merge simple unrelated changes into one batch task to reduce agent spawns.
|
|
34
|
+
- depends_on is only for real output dependencies; most tasks should be parallelizable.
|
|
35
|
+
- Each task should be substantial (15-60 minutes); trivial changes <5 minutes must be merged.
|
|
36
|
+
|
|
37
|
+
## Risk Checklist
|
|
38
|
+
|
|
39
|
+
- Does every task map to an acceptance/requirement ref? A task with no mapping is an out-of-scope artifact.
|
|
40
|
+
- Are convergence.criteria grep-verifiable? Subjective/referential phrasings like "looks correct", "properly configured", "align X with Y" are forbidden — you must write exact strings/values/command output.
|
|
41
|
+
- Do action and implementation contain concrete values? "Update config to match production" is bad — write the exact key/signature/import path. The executor only works from the task JSON; vague instructions produce shallow changes.
|
|
42
|
+
- Is read_first complete? At minimum it includes the modified files themselves + the source-of-truth files from context.
|
|
43
|
+
- Are there file write conflicts within the same wave? Only check `files[]` (write targets); `read_first[]` (read-only) is not a conflict. Detected conflicts must be re-arranged across waves.
|
|
44
|
+
- UI plan: does every delivery wave have ≥1 `[UI-observable]` convergence criterion? Vertical slices — do not split into pure-backend/pure-frontend tasks.
|
|
45
|
+
|
|
46
|
+
## Gate Intent
|
|
47
|
+
|
|
48
|
+
- `context-collected`: upstream context/exploration is loaded; no context source blocks with E001.
|
|
49
|
+
- `plan-generated`: plan.json + tasks are produced by the planner agent (inline planning in the main flow is FORBIDDEN).
|
|
50
|
+
- `plan-checked`: plan-checker passes or minor issues confirmed; boundary grill complete; pressure pass complete.
|
|
51
|
+
- `plan-confirmed`: artifacts are registered only after user confirmation (execute/modify/cancel).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# TDD Task-Chain Generation
|
|
2
|
+
|
|
3
|
+
Protocol for `plan --tdd`: decompose each behavior into a test-first task triplet so the executor is forced through Red-Green-Refactor. This governs how the plan is *shaped*; the executor enforces the cycle at run time.
|
|
4
|
+
|
|
5
|
+
## Iron Law
|
|
6
|
+
|
|
7
|
+
**NO PRODUCTION-CODE TASK WITHOUT A FAILING-TEST TASK BEFORE IT.**
|
|
8
|
+
|
|
9
|
+
Every behavior's GREEN task must `depends_on` its RED task. A plan that ships an implementation task with no preceding test task violates TDD and must be re-generated.
|
|
10
|
+
|
|
11
|
+
## Red-Green-Refactor Triplet
|
|
12
|
+
|
|
13
|
+
For each behavior `B` (derived from requirements or convergence criteria), emit up to three tasks:
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
TASK-{N}a RED Write a failing test for B
|
|
17
|
+
TASK-{N}b GREEN Write minimal code to make B pass (depends_on {N}a)
|
|
18
|
+
TASK-{N}c REFACTOR Clean up B's implementation (depends_on {N}b, optional)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
REFACTOR is omitted when there is nothing to clean. RED and GREEN are never merged or skipped.
|
|
22
|
+
|
|
23
|
+
## Per-task requirements
|
|
24
|
+
|
|
25
|
+
### RED — `type: test`
|
|
26
|
+
|
|
27
|
+
- `action`: write a test describing the expected behavior; it MUST fail before the implementation exists.
|
|
28
|
+
- `convergence.criteria` (grep/run-verifiable):
|
|
29
|
+
- test file exists at `{test_path}`
|
|
30
|
+
- test run exits non-zero (**fails**, not errors)
|
|
31
|
+
- failure message matches the expected behavior gap
|
|
32
|
+
- `meta`: `{ tdd_phase: "red", tdd_group: "{N}" }`
|
|
33
|
+
- Use real code, not mocks (unless the dependency is external). One behavior per test.
|
|
34
|
+
|
|
35
|
+
### GREEN — `type: feature`, `depends_on: [TASK-{N}a]`
|
|
36
|
+
|
|
37
|
+
- `action`: write the simplest code that makes the failing test pass — nothing beyond what the test requires.
|
|
38
|
+
- `convergence.criteria`: the RED test now passes AND all pre-existing tests still pass.
|
|
39
|
+
- `meta`: `{ tdd_phase: "green", tdd_group: "{N}" }`.
|
|
40
|
+
|
|
41
|
+
### REFACTOR — `type: refactor`, `depends_on: [TASK-{N}b]`, optional
|
|
42
|
+
|
|
43
|
+
- `action`: improve structure/naming/duplication without changing behavior.
|
|
44
|
+
- `convergence.criteria`: all tests still pass; no new behavior introduced.
|
|
45
|
+
- `meta`: `{ tdd_phase: "refactor", tdd_group: "{N}" }`.
|
|
46
|
+
|
|
47
|
+
## Convergence quality
|
|
48
|
+
|
|
49
|
+
Criteria must be grep/run/test-verifiable with the exact command or string — never subjective ("looks correct", "properly tested"). Prefer concrete forms like `test exits non-zero` (RED) / `test exits 0` (GREEN) / `<test-command> passes`.
|
|
50
|
+
|
|
51
|
+
## Interaction with plan gates
|
|
52
|
+
|
|
53
|
+
The generated triplets flow through the standard plan checker: dependency correctness must show every GREEN depending on its RED, and the Readiness Gate treats a GREEN task with no preceding RED as a blocking violation.
|