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.
Files changed (173) hide show
  1. package/LICENSE +27 -0
  2. package/README.md +90 -2
  3. package/dist/agent-memory-prompts.d.ts +13 -0
  4. package/dist/agent-memory-prompts.js +55 -0
  5. package/dist/cli.d.ts +2 -0
  6. package/dist/cli.js +6 -0
  7. package/dist/closeout.d.ts +105 -0
  8. package/dist/closeout.js +479 -0
  9. package/dist/code.d.ts +39 -0
  10. package/dist/code.js +124 -0
  11. package/dist/common.d.ts +9 -0
  12. package/dist/common.js +42 -0
  13. package/dist/context-envelope.d.ts +59 -0
  14. package/dist/context-envelope.js +23 -0
  15. package/dist/host-adapters.d.ts +34 -0
  16. package/dist/host-adapters.js +151 -0
  17. package/dist/http.d.ts +3 -0
  18. package/dist/http.js +90 -0
  19. package/dist/index.d.ts +16 -0
  20. package/dist/index.js +13 -0
  21. package/dist/knowledge-cli.d.ts +183 -0
  22. package/dist/knowledge-cli.js +654 -0
  23. package/dist/knowledge-reads.d.ts +71 -0
  24. package/dist/knowledge-reads.js +193 -0
  25. package/dist/memory.d.ts +97 -0
  26. package/dist/memory.js +250 -0
  27. package/dist/retrospective.d.ts +57 -0
  28. package/dist/retrospective.js +248 -0
  29. package/dist/search.d.ts +36 -0
  30. package/dist/search.js +112 -0
  31. package/dist/skill-addition.d.ts +25 -0
  32. package/dist/skill-addition.js +89 -0
  33. package/dist/skill-design.d.ts +96 -0
  34. package/dist/skill-design.js +226 -0
  35. package/dist/skill-replay.d.ts +55 -0
  36. package/dist/skill-replay.js +451 -0
  37. package/dist/skill-route.d.ts +30 -0
  38. package/dist/skill-route.js +75 -0
  39. package/dist/transcript-evidence.d.ts +3 -0
  40. package/dist/transcript-evidence.js +58 -0
  41. package/dist/upstream/chunker.d.ts +24 -0
  42. package/dist/upstream/chunker.js +96 -0
  43. package/dist/upstream/file-protocol.d.ts +45 -0
  44. package/dist/upstream/file-protocol.js +117 -0
  45. package/dist/upstream/frontmatter.d.ts +47 -0
  46. package/dist/upstream/frontmatter.js +86 -0
  47. package/dist/upstream/graph-search.d.ts +33 -0
  48. package/dist/upstream/graph-search.js +67 -0
  49. package/dist/upstream/l1-extraction.d.ts +26 -0
  50. package/dist/upstream/l1-extraction.js +405 -0
  51. package/dist/upstream/llm.d.ts +8 -0
  52. package/dist/upstream/llm.js +1 -0
  53. package/dist/upstream/merge.d.ts +50 -0
  54. package/dist/upstream/merge.js +153 -0
  55. package/dist/upstream/prompts.d.ts +53 -0
  56. package/dist/upstream/prompts.js +185 -0
  57. package/dist/upstream/search-utils.d.ts +34 -0
  58. package/dist/upstream/search-utils.js +55 -0
  59. package/dist/upstream/slug.d.ts +26 -0
  60. package/dist/upstream/slug.js +103 -0
  61. package/dist/upstream/template.d.ts +29 -0
  62. package/dist/upstream/template.js +80 -0
  63. package/dist/upstream/tokenize.d.ts +4 -0
  64. package/dist/upstream/tokenize.js +29 -0
  65. package/dist/wiki-change.d.ts +76 -0
  66. package/dist/wiki-change.js +299 -0
  67. package/dist/wiki-entry.d.ts +26 -0
  68. package/dist/wiki-entry.js +93 -0
  69. package/dist/wiki-ingest.d.ts +12 -0
  70. package/dist/wiki-ingest.js +126 -0
  71. package/dist/wiki-migration.d.ts +16 -0
  72. package/dist/wiki-migration.js +268 -0
  73. package/dist/wiki-tokens.d.ts +1 -0
  74. package/dist/wiki-tokens.js +46 -0
  75. package/dist/wiki.d.ts +103 -0
  76. package/dist/wiki.js +330 -0
  77. package/dist/workflow-cli.d.ts +2 -0
  78. package/dist/workflow-cli.js +258 -0
  79. package/dist/workflow-install.d.ts +36 -0
  80. package/dist/workflow-install.js +148 -0
  81. package/dist/workflow-knowledge.d.ts +16 -0
  82. package/dist/workflow-knowledge.js +24 -0
  83. package/dist/workflow-mcp.d.ts +2 -0
  84. package/dist/workflow-mcp.js +144 -0
  85. package/dist/workflow-names.d.ts +4 -0
  86. package/dist/workflow-names.js +18 -0
  87. package/dist/workflow-runtime.d.ts +622 -0
  88. package/dist/workflow-runtime.js +627 -0
  89. package/dist/workflow-skills.d.ts +48 -0
  90. package/dist/workflow-skills.js +141 -0
  91. package/package.json +76 -4
  92. package/skills/ew-odyssey/SKILL.md +237 -0
  93. package/skills/ew-odyssey/references/audit-artifacts.md +7 -0
  94. package/skills/ew-odyssey/references/odyssey-base-codex.md +3 -0
  95. package/skills/ew-odyssey/references/odyssey-base.md +278 -0
  96. package/skills/ew-odyssey/references/odyssey-debug.codex.md +305 -0
  97. package/skills/ew-odyssey/references/odyssey-debug.md +283 -0
  98. package/skills/ew-odyssey/references/odyssey-defensive.codex.md +395 -0
  99. package/skills/ew-odyssey/references/odyssey-defensive.md +369 -0
  100. package/skills/ew-odyssey/references/odyssey-improve.codex.md +270 -0
  101. package/skills/ew-odyssey/references/odyssey-improve.md +248 -0
  102. package/skills/ew-odyssey/references/odyssey-planex.codex.md +352 -0
  103. package/skills/ew-odyssey/references/odyssey-planex.md +312 -0
  104. package/skills/ew-odyssey/references/odyssey-review.codex.md +283 -0
  105. package/skills/ew-odyssey/references/odyssey-review.md +251 -0
  106. package/skills/ew-odyssey/references/odyssey-security.md +249 -0
  107. package/skills/ew-odyssey/references/odyssey-ui.codex.md +294 -0
  108. package/skills/ew-odyssey/references/odyssey-ui.md +250 -0
  109. package/skills/ew-odyssey/references/prepare/odyssey-debug.md +105 -0
  110. package/skills/ew-odyssey/references/prepare/odyssey-defensive.md +121 -0
  111. package/skills/ew-odyssey/references/prepare/odyssey-improve.md +93 -0
  112. package/skills/ew-odyssey/references/prepare/odyssey-planex.md +104 -0
  113. package/skills/ew-odyssey/references/prepare/odyssey-review.md +98 -0
  114. package/skills/ew-odyssey/references/prepare/odyssey-security.md +94 -0
  115. package/skills/ew-odyssey/references/prepare/odyssey-ui.md +87 -0
  116. package/skills/ew-orchestrate/SKILL.md +236 -0
  117. package/skills/ew-orchestrate/references/auto-policy.md +165 -0
  118. package/skills/ew-orchestrate/references/companion-route.md +52 -0
  119. package/skills/ew-orchestrate/references/ew-orchestrate.md +27 -0
  120. package/skills/ew-orchestrate/references/goal.md +53 -0
  121. package/skills/ew-orchestrate/references/knowledge-route.md +163 -0
  122. package/skills/ew-orchestrate/references/orchestrator-run-loop.md +36 -0
  123. package/skills/ew-orchestrate/references/planning.md +137 -0
  124. package/skills/ew-orchestrate/steps/ew-analyze/SKILL.md +62 -0
  125. package/skills/ew-orchestrate/steps/ew-analyze/references/boundary-grill.md +50 -0
  126. package/skills/ew-orchestrate/steps/ew-analyze/references/issue-gaps-analyze.md +59 -0
  127. package/skills/ew-orchestrate/steps/ew-analyze/references/prepare.md +42 -0
  128. package/skills/ew-orchestrate/steps/ew-analyze/references/workflow.md +401 -0
  129. package/skills/ew-orchestrate/steps/ew-brainstorm/SKILL.md +32 -0
  130. package/skills/ew-orchestrate/steps/ew-companion/SKILL.md +9 -0
  131. package/skills/ew-orchestrate/steps/ew-execute/SKILL.md +71 -0
  132. package/skills/ew-orchestrate/steps/ew-execute/references/prepare.md +69 -0
  133. package/skills/ew-orchestrate/steps/ew-execute/references/workflow.md +373 -0
  134. package/skills/ew-orchestrate/steps/ew-plan/SKILL.md +102 -0
  135. package/skills/ew-orchestrate/steps/ew-plan/references/boundary-grill.md +50 -0
  136. package/skills/ew-orchestrate/steps/ew-plan/references/prepare.md +51 -0
  137. package/skills/ew-orchestrate/steps/ew-plan/references/tdd.md +53 -0
  138. package/skills/ew-orchestrate/steps/ew-plan/references/workflow.md +278 -0
  139. package/skills/ew-orchestrate/steps/ew-review/SKILL.md +44 -0
  140. package/skills/ew-orchestrate/steps/ew-review/references/odyssey-base-codex.md +3 -0
  141. package/skills/ew-orchestrate/steps/ew-review/references/prepare.md +76 -0
  142. package/skills/ew-orchestrate/steps/ew-review/references/workflow.md +283 -0
  143. package/skills/ew-skill-design/SKILL.md +28 -0
  144. package/skills/ew-skill-design/references/package-contract.md +28 -0
  145. package/skills/ew-skill-design/references/validation.md +7 -0
  146. package/skills/team-swarm/SKILL.md +231 -0
  147. package/skills/team-swarm/references/mcp-coordination.md +10 -0
  148. package/skills/team-swarm/roles/analyst/role.md +181 -0
  149. package/skills/team-swarm/roles/ant/role.md +149 -0
  150. package/skills/team-swarm/roles/coordinator/commands/converge.md +154 -0
  151. package/skills/team-swarm/roles/coordinator/commands/init-swarm.md +134 -0
  152. package/skills/team-swarm/roles/coordinator/commands/iterate.md +202 -0
  153. package/skills/team-swarm/roles/coordinator/role.md +228 -0
  154. package/skills/team-swarm/roles/scorer/role.md +150 -0
  155. package/skills/team-swarm/scripts/aco.py +646 -0
  156. package/skills/team-swarm/scripts/pheromone.py +144 -0
  157. package/skills/team-swarm/scripts/scoring.py +111 -0
  158. package/skills/team-swarm/scripts/test_aco.py +606 -0
  159. package/skills/team-swarm/specs/ant-output-schema.md +127 -0
  160. package/skills/team-swarm/specs/convergence-criteria.md +108 -0
  161. package/skills/team-swarm/specs/pheromone-schema.md +125 -0
  162. package/skills/team-swarm/specs/swarm-config-template.json +71 -0
  163. package/skills/team-swarm/specs/swarm-protocol.md +123 -0
  164. package/skills/workflow-closeout/SKILL.md +10 -0
  165. package/skills/workflow-evolve/SKILL.md +79 -0
  166. package/skills/workflow-evolve/references/agy-gate.md +27 -0
  167. package/skills/workflow-evolve/references/auto-loop.md +20 -0
  168. package/skills/workflow-evolve/references/history-review.md +14 -0
  169. package/skills/workflow-evolve/scripts/codex-memory-replay.mjs +76 -0
  170. package/skills/workflow-evolve/scripts/codex-replay.mjs +1 -0
  171. package/skills/workflow-evolve/scripts/evolve-loop.mjs +259 -0
  172. package/skills/workflow-evolve/scripts/memory-codex-mcp.mjs +124 -0
  173. 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.