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,278 @@
1
+ ---
2
+ name: ew-plan
3
+ prepare: plan
4
+ commands: [ew-plan]
5
+ session-mode: inherited
6
+ ---
7
+
8
+ # Workflow: Plan
9
+
10
+ 5-step pipeline: Context Collection → Clarification → Planning → Plan Checking → Confirmation.
11
+
12
+ Produces a two-layer plan: `outputs/plan.json` (overview, with task_ids[] and wave references) + `outputs/tasks/TASK-{NNN}.json` (individual task definitions) + waves/dependency-graph/collision-report.
13
+
14
+ ## Pipeline / FSM
15
+
16
+ ```
17
+ Step 1 Context Collection → Step 2 Clarification → Step 3 Planning → Step 4 Plan Checking → Step 4.5 Collision → Step 5 Confirmation
18
+
19
+ Mode routing:
20
+ --check <plan-dir> → Check Mode (Step 4 only, read-only)
21
+ --revise → Revise Mode (load → modify → Step 4)
22
+ --tdd → TDD Mode: Step 1 → Step 2 → Step 3(TDD task chain) → Step 4 → Step 4.5 → Step 5
23
+ default → Create Mode: Step 1 → Step 2 → Step 3 → Step 4 → Step 4.5 → Step 5
24
+ ```
25
+
26
+ ## Scope Determination
27
+
28
+ ```
29
+ --from <upstream alias> → scope=standalone, seed task generation from the upstream findings' implementation_scope
30
+ --gaps → load issue/debug/review/verification/UAT gaps, skip Step 1 exploration, only plan gap fixes
31
+ numeric arg → scope=milestone, resolve slug from roadmap
32
+ no arg + roadmap → scope=milestone (current milestone)
33
+ no arg + no roadmap → find the most recent analyze artifact; if present standalone, if not E001
34
+ ```
35
+
36
+ Agent mode (auto-selected by scope):
37
+ - **single agent** (default): ≤3 modules, 1 workflow-planner, ≤8 tasks
38
+ - **2+1 agent** (auto-triggered when >3 modules): 2 parallel planners each scoped to 2-3 modules (each ≤8 tasks, total ≤16) + 1 synthesis agent (merge tasks, DAG analysis, cycle detection, cross-module conflicts, terminology consistency, wave ordering) → unified plan.json
39
+
40
+ ## Step Gates (Create mode, mandatory blocking)
41
+
42
+ **GATE: context-collected (Step 1 → Step 2)**
43
+ - upstream context loaded (analyze findings / --from source / roadmap)
44
+ - codebase docs read (if ARCHITECTURE.md / FEATURES.md exist)
45
+ - Wiki searched by phase keywords
46
+ - Blocking: no context source at all → E001
47
+
48
+ **GATE: plan-generated (Step 3 → Step 4)**
49
+ - plan.json + tasks/TASK-*.json written out by the planner agent
50
+ - inline planning in the main flow is FORBIDDEN
51
+ - Blocking: planner produced no plan.json or tasks → cannot proceed to checking
52
+
53
+ **GATE: plan-checked (Step 4 → Step 5)**
54
+ - plan-checker passes (or minor issues confirmed)
55
+ - boundary grill complete
56
+ - confidence scored via the 5-dimension factor model
57
+ - highest-complexity task completed a pressure pass
58
+ - UI plan: every delivery wave has a `[UI-observable]` criterion
59
+ - Blocking: checker found a critical, or a UI plan lacks `[UI-observable]` coverage
60
+
61
+ **GATE: plan-confirmed (Step 5 → wrap-up)**
62
+ - user confirms (execute/modify/cancel)
63
+ - Blocking: no confirmation → don't register artifacts, don't report completion
64
+
65
+ ---
66
+
67
+ ## Process
68
+
69
+ ### Step 1: Context Collection
70
+
71
+ Collect all available context:
72
+
73
+ 1. **Upstream decisions**: read from injected aliases
74
+ - `current-analysis` (findings): `decisions[class=locked]` immutable constraints, `[free]` implementer discretion, `[deferred]` exclusion; `findings[]`/recommendation → task scope. If implementation_scope exists: `scope.objective` → task titles, `scope.acceptance_criteria` → convergence.criteria (grep-ified), `scope.target_files` → files[] + read_first[], `scope.priority` → ordering. When present, skip parallel exploration.
75
+ - `latest-review` (review-findings): BLOCK findings retain finding IDs, severity, evidence, impact, suggestion, and affected files. Normalize each record as `finding_id = finding.id`, `affected_files = [finding.file]`, and `location = finding.file + ":" + finding.line` before deduplication. Cluster related findings by shared root cause/module before planning; do not flatten a cross-module review into ad-hoc execute args.
76
+ - `current-blueprint`: requirements + architecture seed tasks
77
+ - `current-analysis.architecture_template_evidence`: reference-only architecture evidence
78
+ - `blueprint`, `grill`, and `brainstorm` context-package `references[]` entries with `type=architecture-template`
79
+ - research `SUMMARY.md` architecture template evidence, when present
80
+ 2. **Architecture rules**: apply matching `session-priors`. If planning adds architecture or task path scope, use `wiki_context` for that scope before planning against it.
81
+ 3. **Codebase docs**: read `.workflow/codebase/doc-index.json` (if it exists), extract relevant feature/component/requirement
82
+ 4. **Additional knowledge** (optional): look up Wiki evidence for newly added scope and open the references you use. Search working Memory for planning lessons when relevant. If unavailable record W003 and continue.
83
+ 5. **Design reference** (if any): if `design-ref/MASTER.md` exists load design-tokens/animation-tokens/layout; each UI task's read_first[] must include these. For UI work without that reference, use the project's applicable design guidance when planning.
84
+ 6. **Parallel exploration** (skipped when `--gaps` or upstream findings already exist): 1-4 exploration angles (architecture/implementation/integration/risk), spawn 1-4 cli-explore-agent (mandatory, manual Read/Grep is not a substitute), each with goal + success_criteria + one angle → write `{run_dir}/outputs/exploration-{angle}.json`
85
+ 6b. **CLI supplementary context** (parallel with 6, skipped when `--gaps` or no CLI tool): `evolve delegate` collects implementation context (existing patterns, dependency graph, collision points), MODE analysis, after callback parsing merge into explorationContext's `cli_context`
86
+ 7. **Gap mode** (`--gaps`): merge gap sources in this priority order — `.workflow/issues/issues.jsonl` (by phase_ref + status in [registered,diagnosed], mark planning) → `latest-review.findings[]` → `verification.json` gaps → `uat.md` "Gaps" → `latest-debug`/`.debug/*/understanding.md` enrichment. Normalize review records with `finding_id = finding.id`, `affected_files = [finding.file]`, and `location = finding.file + ":" + finding.line`; then retain `{finding_id, description, suggestion as fix_direction, severity, evidence, impact, affected_files, location, source:"review"}`. Deduplicate by issue/finding ID first, then normalized root cause + affected files. Cluster review findings that share a root cause/module so the final plan remains within the normal task-count guardrails. If all sources are empty, report error. Set `explorationContext = all_gaps` (skip exploration agents).
87
+
88
+ ### Step 2: Clarification (interactive)
89
+
90
+ `--auto`/`-y` skips.
91
+
92
+ 1. Aggregate each exploration's `clarification_needs[]`, deduplicate, sort by blocking > important > nice-to-have
93
+ 2. Interactive clarification (up to 3 rounds, up to 4 questions each), AskUserQuestion, record answers and follow-ups
94
+ 3. Construct `clarificationContext = { questions_asked, answers, decisions_made }`
95
+
96
+ ### Step 3: Planning
97
+
98
+ **Rules**:
99
+ - The main flow MUST spawn a planner agent (Agent tool); inline planning is FORBIDDEN
100
+ - The agent produces plan.json and tasks/TASK-{NNN}.json; the main flow MUST NOT create/modify these files
101
+ - Upstream findings (including implementation_scope) MUST be passed into the planner's explorationContext in the same step
102
+
103
+ **Standard mode**: spawn workflow-planner, passing upstream context, spec-ref, doc-index, explorationContext, clarificationContext, `architecture_template_evidence`, goal + success_criteria. The planner consumes but does not search/load template references.
104
+
105
+ Task-count guardrails (assess complexity before spawning): single feature/simple change ≤4 tasks; medium (multi-file cross-module) ≤8; large milestone (>3 modules, 2+1) ≤16. If exceeded, re-prompt requesting consolidation.
106
+
107
+ Agent responsibilities:
108
+ 1. Decompose goal into tasks (with implementation_scope, 1 scope item → 1 task)
109
+ 2. Assign task IDs (TASK-001…), define dependencies
110
+ 3. Group into waves (with scope, order by priority)
111
+ 4. Estimate complexity/time
112
+ 5. Set grep-verifiable convergence.criteria (when scope.acceptance_criteria exists, generate from it)
113
+ 6. Define files per task (from scope.target_files when present), fill read_first[]
114
+ 7. Pass the evaluated `architecture_template_evidence` envelope to the planner. Store its `{status, query}` in `plan.json.shared_context.architecture_template_search` and only its `templates[]` records in `plan.json.shared_context.architecture_templates`; relevant tasks may reference only resolved `template_id` values in `reference.architecture_template_refs`.
115
+
116
+ **Deep Work rules** (mandatory in all modes, every TASK JSON must include):
117
+
118
+ 1. **read_first** — what the executor must read before acting: the files being modified + source-of-truth files in the context + any file whose pattern/signature/type/convention must be replicated or followed
119
+ 2. **convergence.criteria** — grep/read/test/CLI verifiable; no subjective language ("looks correct", "properly configured", "consistent with"); must contain the exact string/pattern/value/command output. E.g.: `auth.ts contains export function verifyToken(` / `test exits 0` / `.env.example contains DATABASE_URL=`
120
+ 3. **action** — contains concrete values not references; no "align X with Y"/"match X to Y" without specifying the exact target state; contains actual config key/function signature/class name/import path; if the context has a reference table, copy it in verbatim
121
+ 4. **implementation** steps — each step contains concrete values. Bad: "Update config to match production"; Good: "Add DATABASE_URL=postgresql://..., set POOL_SIZE=20, add REDIS_URL=redis://..."
122
+
123
+ **Why it matters**: the executor works only from the task JSON; vague instructions produce a shallow one-line change, specific instructions produce complete work.
124
+
125
+ **Anti-splitting** (passed to the planner, re-prompt on violation): one feature one task (even across 3-5 files, never split by file); consolidate simple unrelated changes into a batch task; use depends_on only for real output dependencies; each task must be substantial (15-60 minutes), fold <5-minute trivial changes together; **UI vertical slice** — a user-visible feature is one end-to-end task/wave (backend endpoint + frontend wiring + integration), never split into pure-backend/pure-frontend; each UI delivery wave has ≥1 task with a `[UI-observable]` criterion.
126
+
127
+ **Gap mode (`--gaps`)**: spawn workflow-planner, mode=`gap-fix`. Use one task per independent gap or clustered root cause: `type: fix`, `description`, `action` (concrete fix_direction), `read_first` (affected files), `convergence.criteria` (grep-ified), `issue_id` (when source==issue), and `finding_refs[]` (when source includes review); assign ID and wave. After the planner, the main flow back-links bidirectionally: matched issue → `status: planned`; review finding IDs remain immutable requirement references in the generated tasks.
128
+
129
+ ### Step 4: Plan Checking
130
+
131
+ 1. **spawn workflow-plan-checker** (mandatory, not substitutable): input plan.json + all tasks + success_criteria + inherited `architecture_template_evidence`. Check dimensions: requirements coverage, feasibility, dependency correctness (no cycles), convergence quality (grep-verifiable, no subjective language), read_first completeness, action specificity (no vague references), wave structure (no colliding files), completeness (no orphan tasks), UI-observable coverage, and architecture-template evidence. The checker does not search/load templates.
132
+ 2. **Architecture-template evidence checks**: `shared_context.architecture_template_search` contains only the envelope status/query and `shared_context.architecture_templates` is an array of records; every task template ID resolves to an array record; only `source=arch-kb`, `kind=template`, `reference_only=true` records are valid; adopted/adapted records require rationale and non-empty `applies_to`; a non-loaded status or candidate/rejected record cannot become a task requirement; template IDs remain absent from project-knowledge consumption fields.
133
+ 3. **Revision loop** (up to 3 rounds): critical → re-spawn planner to revise and re-check; warning only → record and continue
134
+ 4. **Confidence scoring**: 5 dims (requirements_coverage, task_quality, dependency_correctness, estimation_accuracy, collision_safety) × factors (completeness .30, specificity .25, structural_validity .20, user_validation .15, consistency .10). Re-score each round. Quality mechanisms: Pressure Pass (mandatory before Step 4.5, verifies the highest-complexity task's read_first/convergence/action), Devil's Advocate (coverage>0.7 → "implicit requirement?"), Scope Minimizer, Stall Detection
135
+ 5. **Readiness Gate** (blocks Step 4.5): blocking conditions — coverage<40% | a task missing read_first/convergence | no pressure pass | circular dependency | invalid architecture-template reference. If blocked → AskUserQuestion: revise / ignore risk and continue (record residual_risks)
136
+
137
+ ### Step 4.5: Collision Detection
138
+
139
+ `scope==standalone` skips (no milestone to compare against).
140
+
141
+ ```
142
+ 1. Collect task.files[] from all completed plans in the same milestone
143
+ 2. Collect the new plan's task.files[]
144
+ 3. Intersect → collisions (non-blocking warning)
145
+ collision → WARN "{file} ← already planned in {plan_ids}"
146
+ no overlap → "collision check passed"
147
+ ```
148
+ Only check `task.files[]` (write targets); `read_first[]` (read-only references) is excluded.
149
+
150
+ ### Step 5: Confirmation
151
+
152
+ Planner, checker, revise, and check mode do not perform a new template search or load; they consume inherited evidence only.
153
+
154
+ 1. **Present plan summary**: objective, approach, task count, wave structure, complexity, key dependencies, plan confidence (overall %, weakest dimension, pressure pass result)
155
+ 2. **AskUserQuestion** (skip and auto-pass if `config.gates.confirm_plan == false`): Execute now / Verify plan quality (re-run Step 4 more strictly) / Just view / Modify (change specified tasks, back to Step 4)
156
+
157
+ ---
158
+
159
+ ## Output Skeleton
160
+
161
+ **outputs/plan.json**:
162
+ ```json
163
+ {
164
+ "objective": "",
165
+ "requirement_refs": [],
166
+ "task_ids": [],
167
+ "wave_ids": [],
168
+ "confidence": 0,
169
+ "constraints": [],
170
+ "acceptance_criteria": [],
171
+ "shared_context": {
172
+ "architecture_template_search": null,
173
+ "architecture_templates": []
174
+ }
175
+ }
176
+ ```
177
+
178
+ `plan/1.0` also admits an externally approved plan with `{ source_format: "pi-markdown", handoff_key, source_checksum, source_pi_session, revision, approved_at, markdown }` plus the standard `_meta`. In that variant `markdown` is the complete authoritative Plan; downstream steps use their `pi-markdown` interpretation branch.
179
+
180
+ **outputs/tasks/TASK-NNN.json** (multiple files of the same kind, needs `_meta` override):
181
+ ```json
182
+ {
183
+ "_meta": { "kind": "plan-task", "schema": "plan-task/1.0", "role": "attachment" },
184
+ "id": "TASK-001",
185
+ "title": "",
186
+ "description": "",
187
+ "requirement_refs": [],
188
+ "deps": [],
189
+ "files": [],
190
+ "read_first": [],
191
+ "convergence_criteria": [],
192
+ "verify": [],
193
+ "status": "pending"
194
+ }
195
+ ```
196
+
197
+ **outputs/waves.json**, **outputs/dependency-graph.json**, **outputs/collision-report.json**. If a plan check runs, write `outputs/plan-check.json`.
198
+
199
+ ### report frontmatter
200
+
201
+ Write `report.md`, frontmatter containing at least `verdict`, `summary`, `constraints`, `decisions`, `concerns` plus:
202
+ ```yaml
203
+ next:
204
+ - { command: ew-execute, reason: plan ready, needs: [current-plan] }
205
+ ```
206
+ Body has fixed sections `Summary`, `Conclusion/Verdict`, `Discussion/Retrospective`, `Artifacts`, `Handoff/Next`, reference `current-plan` via aref, never copy the JSON source of truth.
207
+
208
+ → Wrap-up (archiving, spec/knowhow candidate extraction) follows ref/finish-work.md — staging happens BEFORE seal; the corpus is written only via post-seal promote.
209
+
210
+ ---
211
+
212
+ ## Success Criteria
213
+
214
+ - [ ] Upstream context loaded (analysis/debug/blueprint/roadmap)
215
+ - [ ] Scope determined (single-agent ≤3 modules or 2+1 agent >3 modules)
216
+ - [ ] plan.json generated by planner agent (not inline)
217
+ - [ ] Every task has acceptance ref, dependencies, expected files, convergence criteria
218
+ - [ ] Convergence criteria are grep-verifiable (no subjective language)
219
+ - [ ] Wave DAG has no file write conflicts within same wave
220
+ - [ ] Plan-checker passed (or minor issues confirmed)
221
+ - [ ] Architecture-template evidence is resolved, recorded, and reference-only
222
+ - [ ] User confirmed (execute/modify/cancel)
223
+
224
+ ---
225
+
226
+ ## Domain Invariants
227
+
228
+ - Every task must map to an acceptance/requirement ref, declare dependencies, expected files, verification method, and convergence criteria.
229
+ - convergence.criteria must be grep-verifiable, no subjective language.
230
+ - action/implementation must contain concrete values, no vague references.
231
+ - Inline planning in the main flow is FORBIDDEN; plan.json and tasks are produced only by the planner agent.
232
+ - Architecture template IDs must resolve from `plan.json.shared_context.architecture_templates` and must not appear in project-knowledge consumption fields.
233
+ - A UI plan must have a `[UI-observable]` criterion in every delivery wave; vertical slices cannot be split into pure front/back-end.
234
+
235
+ ## Revise Mode (`--revise`)
236
+
237
+ Incrementally modify an existing plan, do not rebuild.
238
+
239
+ 1. **Discover plan**: if `--dir` is specified use it directly; otherwise take the most recent completed plan of the current milestone; if none E004
240
+ 2. **Load**: read plan.json + all tasks, show current summary (task count, waves, per-task status). Inherit any `architecture_template_evidence`; do not search/load templates.
241
+ 3. **Get revision instructions**: `--revise "instructions"` parsed into change directives; if no instructions AskUserQuestion (add/remove tasks / modify scope-action-implementation / reorder waves or dependencies / update convergence)
242
+ 4. **spawn workflow-planner to revise**: input existing plan.json + tasks + parsed instructions + explorationContext + templates + inherited architecture evidence. Planner: modify affected tasks in place; on add/remove reorder IDs and waves; update plan.json summary; preserve unchanged tasks without a new template search/load
243
+ 5. **Re-run Step 4** + collision, show results and confirm
244
+ 6. **Update artifacts**: overwrite plan files in the existing directory (don't create new artifacts)
245
+
246
+ ## Check Mode (`--check`)
247
+
248
+ Read-only validation, no file changes.
249
+
250
+ 1. Load plan.json + tasks (if none E005) + roadmap from the `--check` path; consume any plan-level `shared_context.architecture_templates` only.
251
+ 2. Run plan-checker (task quality, convergence), roadmap consistency, collision, dependency completeness; do not search/load templates
252
+ 3. Produce report:
253
+ ```
254
+ === PLAN CHECK ===
255
+ Plan: {plan_dir}/plan.json
256
+ Tasks: {total} ({completed} done, {pending} pending)
257
+ Checker: {PASS|WARN|FAIL} ({issues} issues)
258
+ Roadmap: {aligned|drift detected}
259
+ Collision: {clear|{N} overlaps}
260
+ ```
261
+
262
+ ---
263
+
264
+ ## Error Codes
265
+
266
+ | Code | Condition | Recovery |
267
+ |------|-----------|----------|
268
+ | E001 | No arg no roadmap | Provide a milestone number or topic, or create a roadmap first |
269
+ | E004 | No plan to revise | Specify `--dir`, or create a plan first |
270
+ | E005 | Plan directory not found (--check) | Check the path or use `--dir` |
271
+ | E006 | Planner produced invalid JSON | Retry once, then abort with details |
272
+ | W001 | Exploration agent failed | Record, continue with existing exploration; mark plan [LOW CONFIDENCE] |
273
+ | W002 | Plan-checker exceeded 3 rounds | Accept the plan with warnings, record in index; mark [LOW CONFIDENCE] |
274
+
275
+ ## Knowledge Hooks
276
+
277
+ - Stage locked constraints and accepted decisions in `report.md` frontmatter (`constraints`/`decisions`); sealing converts them to spec candidates.
278
+ - Include verified reusable planning methods in the Run summary and use Agent Memory closeout after Session completion.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: ew-review
3
+ description: Review a change or artifact inside the Evolve chain and produce typed findings
4
+ argument-hint: '<target> [--tier quick] [-y]'
5
+ wiki_categories: [review, coding]
6
+ search_profile:
7
+ wiki: [constraints, references]
8
+ memory: [error, correction, verified_fix]
9
+ session-mode: run
10
+ required_links:
11
+ - references/prepare.md
12
+ - references/workflow.md
13
+ contract:
14
+ consumes:
15
+ - kind: artifact
16
+ alias: current-execution
17
+ required: false
18
+ schema: artifacts/1.0
19
+ role: primary
20
+ - kind: priors
21
+ alias: session-priors
22
+ required: false
23
+ schema: priors/1.0
24
+ role: evidence
25
+ produces:
26
+ - path: outputs/review.json
27
+ kind: review-findings
28
+ alias: latest-review
29
+ role: primary
30
+ required: true
31
+ schema: review-findings/1.0
32
+ contract_version: 2.1
33
+ ---
34
+
35
+ # Review
36
+
37
+ Review is a quality step inside the Evolve Skill. Use the linked preparation and workflow documents for the full review protocol.
38
+
39
+ - Read [review preparation](references/prepare.md) before defining the audit scope.
40
+ - Read [review workflow](references/workflow.md) for the four dimensions, evidence format and zero-residual gate.
41
+ - Reuse the bound `session-priors` for the same Wiki scope. Search for additional evidence when the scope changes.
42
+ - Write `outputs/review.json` with file and line evidence, severity, remediation and verification status.
43
+
44
+ The review step reports findings and follows the confirmed Session chain. It does not create a separate orchestration entry.
@@ -0,0 +1,3 @@
1
+ <!-- session-mode: inherited -->
2
+
3
+ # Odyssey Shared Base (Codex)
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: ew-odyssey-review
3
+ description: "Odyssey review mode — multi-dimensional deep code review through archaeology, exploration, 4-dimension audit, exhaustive severity-tiered fix, and zero-residual confirmation, producing review"
4
+ argument-hint: "<target: file|dir|HEAD|staged|phase#|PR#> [--skip-fix] [--skip-generalize] [-y] [-c]"
5
+ contract:
6
+ goal: true
7
+ ---
8
+
9
+ # Pre-task Thinking: odyssey-review
10
+
11
+ ## Purpose
12
+
13
+ Odyssey review is a full-lifecycle code review cycle: target intake → archaeology → code exploration → multi-dimensional review audit → exhaustive severity-tiered fix → zero-residual confirmation → generalization → discovery → knowledge persistence. Unlike standalone code review (which produces only findings), odyssey-review carries through to fix ALL findings by severity, confirm zero residual, generalize patterns project-wide, and persist learnings.
14
+
15
+ ## Input Interpretation
16
+
17
+ Entry modes:
18
+
19
+ | Mode | Trigger | Target source |
20
+ |------|---------|---------------|
21
+ | file/dir | file or directory path in `<intent>` | Review those files directly |
22
+ | diff | `HEAD` or `staged` in `<intent>` | `git diff HEAD` or `git diff --staged` |
23
+ | phase | phase number in `<intent>` | state.json → changed files for that phase |
24
+ | PR | PR number in `<intent>` | `git diff main...HEAD` |
25
+ | continuation | `-c` | Resume via latest session, jump to `current_state` |
26
+
27
+ Target resolution table:
28
+
29
+ | Input | Resolution |
30
+ |-------|-----------|
31
+ | File/dir path | Review those files |
32
+ | `HEAD` / `staged` | `git diff HEAD` / `git diff --staged` |
33
+ | Phase number | state.json → changed files |
34
+ | PR number | `git diff main...HEAD` |
35
+
36
+ ## Required Context
37
+
38
+ Context injection (optional, may continue if missing):
39
+
40
+ - Architecture doc: `.workflow/codebase/ARCHITECTURE.md` → module boundaries, ownership
41
+ - Open bound `session-priors` for the same Wiki scope. When the audit adds review or coding categories or target paths, use `wiki_context` for that scope and open selected references.
42
+ - Memory: `agent-memory memory search "<target keywords>" --type error --scene review` → select relevant IDs and read them with `agent-memory memory get <id>`
43
+
44
+ When prior review artifacts of the same scope exist, check their findings first to avoid re-reviewing already-addressed patterns.
45
+
46
+ ## Boundaries and Invariants
47
+
48
+ - **State chain:** `S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_REVIEW → S_FIX → S_CONFIRM → [back-half]`
49
+ - **Zero-residual applies** — fix ALL findings within fix_threshold (default: all severity levels). No partial-tier advancement.
50
+ - **Evidence append-only** — evidence.ndjson entries are immutable observations; modifying or deleting them is forbidden.
51
+ - **Phase goal tracking** — mark each goal done/failed before transition; no silent skips.
52
+ - **4-dimension mandatory** — all dimensions (correctness, security, performance, architecture) must be reviewed. Zero dimensions reviewed is BLOCKED.
53
+ - **Exhaustive fix by severity** — descend through [critical, high, medium, low], each tier fully addressed before advancing. Blanket "pre-existing" classification forbidden; each finding must be individually assessed.
54
+ - **max_fix_rounds = 5** — hard limit on fix retry rounds. After 5 rounds with remaining > 0, escalate to user or classify as deferred.
55
+ - **Test evidence reuse across S_FIX/S_CONFIRM** — a per-tier commit invalidates only tests covering the committed changes; unchanged passing results carry forward, and S_CONFIRM reruns only invalidated targets plus the modified-area re-review. Never rerun the full matrix merely because a tier advanced.
56
+ - **Generalize is mandatory** unless `skip_generalize == true`; prior-phase convergence is NOT a valid skip reason.
57
+ - **Fix scope:** source code modifications during fix phase are in-scope but MUST be committed per tier. Session artifacts target `{run_dir}/outputs/` only.
58
+ - **In scope:** Multi-dimensional deep review → exhaustive fix → generalize. **Out of scope:** Root cause debug → `--mode debug` | Feature implementation → `--mode planex` | UI visual optimization → `--mode ui`.
59
+
60
+ ## Risk Checklist
61
+
62
+ - Are all 4 review dimensions (correctness, security, performance, architecture) covered? Missing a dimension leaves an entire class of findings undetected.
63
+ - Is every finding backed by file, line, and description evidence? Vague findings without location are not actionable.
64
+ - Did you descend severity tiers in order (critical → high → medium → low)? Skipping tiers leaves high-severity issues unfixed.
65
+ - Is every finding in a tier either fixed or individually classified with a reason? Blanket "pre-existing" skips are forbidden.
66
+ - Have fix rounds exceeded 5? Stop and escalate — do not continue fixing indefinitely.
67
+ - Are archaeology/explore results properly logged even on partial failure (W003/W006)? Missing evidence must be flagged, not silently omitted.
68
+ - Is every discovery hit individually classified with a reason? Blanket skips are forbidden.
69
+ - Are all 3 generalization layers (syntax/semantic/structural) attempted? A single-layer quick grep does NOT satisfy the thoroughness floor.
70
+ - Did the zero-residual confirmation actually re-review modified areas? A pass-through without re-review does not satisfy the CONFIRM gate.
71
+
72
+ ## Gate Intent
73
+
74
+ - `discovery-complete`: archaeology and/or exploration phases have logged evidence, understanding.md §2-§3 are updated, and explore goal (G2) is marked. Archaeology partial results via W003 are acceptable; explore skip via W006 is acceptable if no CLI tools are available.
75
+ - `all-dimensions-reviewed`: all 4 dimension agents (correctness, security, performance, architecture) have completed, findings are merged into review_result with severity classification, evidence phase=review is logged, and understanding.md §4 severity matrix is written. G1 is marked. Zero dimensions reviewed is BLOCKED (W002 partial with at least 1 dimension is allowed).
76
+ - `zero-remaining`: exhaustive fix has been applied tier-by-tier, `remaining_actionable == 0` (or all remaining individually classified as deferred after 5-round escalation), tests covering the modified areas pass (reusing still-valid live-run results from S_FIX rounds when nothing they cover changed since; rerunning only invalidated targets), CLI re-review confirms no new findings, confirmation is written, understanding.md §5 is updated, and G3 is marked. `needs_rework` routes back to FIX. Skippable only when `skip_fix == true`.