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,401 @@
|
|
|
1
|
+
# Workflow: Analyze
|
|
2
|
+
|
|
3
|
+
Multi-dimensional iterative analysis: CLI exploration → multi-perspective synthesis → discussion timeline → intent tracking → six-dimension scoring → decision extraction. Preserves macro/micro, quick, gaps, and up-to-5-round convergence semantics.
|
|
4
|
+
|
|
5
|
+
## Pipeline / FSM
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
Full mode (-q absent):
|
|
9
|
+
Step 1: Setup & Scoping → session init, dimension selection, report discussion area init
|
|
10
|
+
│
|
|
11
|
+
Step 2: CLI Exploration → outputs/exploration-codebase.json, outputs/perspectives.json
|
|
12
|
+
│ (cli-explore-agent three layers + multi-CLI parallel)
|
|
13
|
+
│
|
|
14
|
+
Step 3: Interactive Discussion → report.md discussion section (up to 5 rounds)
|
|
15
|
+
│ (Decision Recording, Intent Coverage)
|
|
16
|
+
│
|
|
17
|
+
Step 4: Six-Dimension Scoring → 6 dims × 1-5 points + risk matrix
|
|
18
|
+
│
|
|
19
|
+
Step 5: Synthesis & Conclusion → outputs/findings.json, report.md conclusion area
|
|
20
|
+
│
|
|
21
|
+
Step 6: Decision Extraction → findings.json#decisions (Locked/Free/Deferred)
|
|
22
|
+
|
|
23
|
+
Quick mode (-q):
|
|
24
|
+
Step 1: Setup (minimal) → load upstream, skip scoping
|
|
25
|
+
│
|
|
26
|
+
Step 6: Decision Extraction → findings.json#decisions
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Mode Determination
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
First positional arg is pure digits (^\d+$) → micro, milestone-level deep-dive
|
|
33
|
+
First positional arg is non-numeric text → macro, topic impact scope
|
|
34
|
+
No positional arg + has roadmap → current milestone micro
|
|
35
|
+
No positional arg + no roadmap → macro fallback
|
|
36
|
+
Mixed input (e.g. "1 milestone") → handled as text, goes macro
|
|
37
|
+
--gaps [ISS-ID] → gaps, goes issue root-cause analysis ([issue gap analysis](issue-gaps-analyze.md))
|
|
38
|
+
-q → quick, skip Step 2-5, jump directly to Step 6
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
macro mode additionally evaluates `scope_verdict` during Step 5 synthesis:
|
|
42
|
+
- `large`: 3+ independent subsystems, or a hard serial dependency barrier exists → downstream goes roadmap
|
|
43
|
+
- `medium`: 1-2 subsystems, parallelizable → downstream goes plan
|
|
44
|
+
- `small`: single file or few-file change → downstream goes plan
|
|
45
|
+
|
|
46
|
+
## Step Gates (Full mode, active when both `-q` and `--gaps` are absent)
|
|
47
|
+
|
|
48
|
+
Mandatory and blocking. Cannot advance if any gate is unmet.
|
|
49
|
+
|
|
50
|
+
**GATE: exploration-done (Step 2 → 3)**
|
|
51
|
+
- cli-explore-agent complete, `outputs/exploration-codebase.json` written and contains ≥1 code anchor
|
|
52
|
+
- ≥1 CLI delegate complete, output landed in `outputs/perspectives.json`
|
|
53
|
+
- discussion area records baseline confidence score
|
|
54
|
+
|
|
55
|
+
**GATE: discussion-round (Step 3 → 4)**
|
|
56
|
+
- discussion area contains ≥1 round of interaction with user feedback
|
|
57
|
+
- confidence re-scored ≥1 time and delta shown
|
|
58
|
+
- pressure pass completed ≥1 time
|
|
59
|
+
|
|
60
|
+
**GATE: scoring-complete (Step 4 → 5)**
|
|
61
|
+
- all six dimensions scored
|
|
62
|
+
- each dimension's score cites exploration/perspectives evidence, **not manual Read**
|
|
63
|
+
|
|
64
|
+
**GATE: intent-covered (Step 5 → 6)**
|
|
65
|
+
- findings.json decisions and recommendations written
|
|
66
|
+
- Intent Coverage Matrix has no unhandled ❌ (or user confirms defer)
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Process
|
|
71
|
+
|
|
72
|
+
### Step 1: Setup & Scoping
|
|
73
|
+
|
|
74
|
+
Parse mode/flags (see above). Load upstream and project context:
|
|
75
|
+
|
|
76
|
+
1. Upstream typed artifacts: read only from injected alias→path (`current-guidance`/`current-blueprint`/`latest-debug`), do not guess latest by mtime.
|
|
77
|
+
- locked constraints → skip (already decided)
|
|
78
|
+
- open constraints → analyze first
|
|
79
|
+
- open questions → discussion seeds
|
|
80
|
+
- `architecture_template_evidence` → architecture analysis context; reuse it without a new search/load
|
|
81
|
+
2. Architecture rules: use `wiki_context` for the analysis topic. Include the path or architecture category in `scope` when the analysis needs those filters.
|
|
82
|
+
3. domain glossary: read `.workflow/domain/glossary.yaml` (if it exists), use canonical terms throughout the analysis; record new term candidates in the report.
|
|
83
|
+
4. Existing same-milestone analyze artifacts: read their decisions, skip already-decided areas.
|
|
84
|
+
5. Open the references selected from `wiki_context` with `wiki_reference`. For execution lessons, use `memory_search` and open relevant IDs with `memory_get`.
|
|
85
|
+
|
|
86
|
+
**quick routing**: after loading context, jump directly to Step 6.
|
|
87
|
+
|
|
88
|
+
**Scoping & dimension selection** (skipped when `-c`/`-y`, interactive AskUserQuestion, up to 3 questions):
|
|
89
|
+
|
|
90
|
+
1. **Analysis direction** (multiSelect), take 3-4 items from the dimension-direction mapping:
|
|
91
|
+
|
|
92
|
+
| Dimension | Direction |
|
|
93
|
+
|------|------|
|
|
94
|
+
| architecture | System Design, Component Interactions, Technology Choices, Design Patterns |
|
|
95
|
+
| implementation | Code Structure, Patterns, Error Handling, Algorithm Analysis |
|
|
96
|
+
| performance | Bottlenecks, Optimization, Resource Utilization, Concurrency |
|
|
97
|
+
| security | Vulnerabilities, Auth, Data Protection, Input Validation |
|
|
98
|
+
| concept | Foundation, Core Mechanisms, Patterns, Trade-offs |
|
|
99
|
+
| comparison | Solution Comparison, Pros/Cons, Technology Evaluation |
|
|
100
|
+
| decision | Criteria, Trade-off Analysis, Risk Assessment, Impact |
|
|
101
|
+
| external_research | Standard Stack, Architecture Patterns, Don't Hand-Roll, Common Pitfalls (external web search) |
|
|
102
|
+
|
|
103
|
+
When the goal contains unfamiliar technology keywords, or the codebase has no pattern for that domain (Step 2 exploration relevant_files is empty), automatically suggest `external_research`.
|
|
104
|
+
|
|
105
|
+
2. **Analysis perspective** (multiSelect, up to 4):
|
|
106
|
+
|
|
107
|
+
| Perspective | CLI | Focus |
|
|
108
|
+
|------|-----|------|
|
|
109
|
+
| Technical | gemini | implementation, code patterns, feasibility |
|
|
110
|
+
| Architectural | claude | system design, scalability, interactions |
|
|
111
|
+
| Business | codex | value, ROI, stakeholder impact |
|
|
112
|
+
| Domain Expert | gemini | domain patterns, best practices, standards |
|
|
113
|
+
|
|
114
|
+
3. **Analysis depth** (single): Quick Overview / Standard / Deep Dive
|
|
115
|
+
|
|
116
|
+
**Auto (-y) defaults**: all relevant dimensions, single synthesis perspective, Standard depth.
|
|
117
|
+
|
|
118
|
+
Initialize report.md discussion area: dynamic TOC, session metadata, User Intent (original question, for intent tracking), Current Understanding replaceable block (overwritten each round, not appended), empty discussion timeline, dimension selection rationale.
|
|
119
|
+
|
|
120
|
+
### Step 2: CLI Exploration
|
|
121
|
+
|
|
122
|
+
Codebase exploration first, then (optional) external research, then CLI analysis.
|
|
123
|
+
|
|
124
|
+
**Step 2.0 Research handoff** (when `external_research` is selected, or when architecture patterns are active and upstream `architecture_template_evidence` is absent):
|
|
125
|
+
1. Only when `external_research` is selected, run WebSearch for 2-3 queries: `"{goal} standard library stack"`, `"architecture patterns best practices"`, `"common pitfalls mistakes"`; take top 1-2 per query and fetch official docs.
|
|
126
|
+
2. Hand available web results and any upstream `architecture_template_evidence` to workflow-phase-researcher. When architecture patterns are active and the envelope is absent, the researcher follows the shared Architecture Template References rule and performs one focused search/load. Do not search for implementation-only phases.
|
|
127
|
+
3. Ask the researcher to synthesize available material into: `## Standard Stack` (with versions), `## Architecture Patterns`, `## Don't Hand-Roll`, `## Common Pitfalls`, and `## Architecture Template Evidence` when applicable. Style: prescriptive ("use X"), cite sources, mark HIGH/MEDIUM/LOW. The agent returns markdown only and writes no files.
|
|
128
|
+
4. Store the result as `researchContext` (in-memory). If neither dispatch condition applies, set `researchContext = null`.
|
|
129
|
+
|
|
130
|
+
**Architecture template handoff**:
|
|
131
|
+
- Reuse upstream `architecture_template_evidence` when present; otherwise dispatch `workflow-phase-researcher` for one focused template search/load whenever architecture patterns are an active dimension, independently of external web research.
|
|
132
|
+
- Preserve the optional evidence envelope and its `no_match` or `load_failed` status in the analysis artifacts; downstream analysis does not search again.
|
|
133
|
+
|
|
134
|
+
**Step 2.1 Codebase exploration** (cli-explore-agent, mandatory, not substitutable):
|
|
135
|
+
|
|
136
|
+
MUST spawn cli-explore-agent; manual Read/Grep is not a substitute. Three layers:
|
|
137
|
+
|
|
138
|
+
| Layer | Focus | Output |
|
|
139
|
+
|----|------|------|
|
|
140
|
+
| L1 Module discovery (breadth) | search by keywords, identify all relevant files, draw module boundaries | `relevant_files[]` |
|
|
141
|
+
| L2 Structure tracing (depth) | top 3-5 key files: trace call chains 2-3 layers, identify data flows | `call_chains[]`, `data_flows[]` |
|
|
142
|
+
| L3 Code anchors (detail) | extract 20-50 line snippet + file:line for each key finding | `code_anchors[]` |
|
|
143
|
+
|
|
144
|
+
Output `outputs/exploration-codebase.json` (single perspective) or `outputs/explorations/{perspective}.json` (multi-perspective, up to 4 parallel).
|
|
145
|
+
|
|
146
|
+
**Step 2.2 CLI analysis** (after exploration, mandatory, not substitutable):
|
|
147
|
+
|
|
148
|
+
MUST have at least one CLI delegate. The orchestrator's own analysis does not count as independent verification — the CLI provides cross-validation from another model/perspective.
|
|
149
|
+
|
|
150
|
+
Construct exploration context from Step 2.1 findings then spawn. When `researchContext` exists, append:
|
|
151
|
+
```
|
|
152
|
+
"External research findings (treat as strong recommendations, not laws):
|
|
153
|
+
{researchContext}"
|
|
154
|
+
```
|
|
155
|
+
- Single perspective: one synthesis CLI call
|
|
156
|
+
- Multi-perspective (up to 4): parallel call per perspective, each with its perspective focus
|
|
157
|
+
|
|
158
|
+
CLI calls use `run_in_background: true`, wait for results before continuing.
|
|
159
|
+
|
|
160
|
+
**Step 2.3 Aggregation**: merge explorations + CLI results; for multi-perspective, extract synthesis (converging themes, conflicting views, unique contributions); write `outputs/perspectives.json`. It contains `technical_solutions[]`: `{round, solution, problem, rationale, alternatives, status: proposed|validated|rejected, evidence_refs[], next_action}`, filled across the Step 3 rounds.
|
|
161
|
+
|
|
162
|
+
**Step 2.4 Round 1**: append to discussion timeline — sources, key findings with code anchors, discussion points, open questions.
|
|
163
|
+
|
|
164
|
+
**Step 2.5 Initial Intent check**: re-read User Intent, cross-check each item against Round 1: ✅ addressed / 🔄 in-progress / ❌ not touched.
|
|
165
|
+
|
|
166
|
+
**Step 2.6 baseline confidence**: 6 dims × factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each dimension. Thresholds: <60% keep going deeper | 60-80% needs user confirmation to converge | >80% proceed to synthesis (necessary convergence threshold).
|
|
167
|
+
|
|
168
|
+
### Step 3: Interactive Discussion Loop
|
|
169
|
+
|
|
170
|
+
Up to 5 rounds, each round:
|
|
171
|
+
|
|
172
|
+
**3.1 Current Understanding** (Round ≥ 2, before new findings): 1-2 sentences bridging the previous round's conclusions to this round's starting point.
|
|
173
|
+
|
|
174
|
+
**3.2 Present findings** from the latest exploration/analysis.
|
|
175
|
+
|
|
176
|
+
**3.3 Collect feedback** AskUserQuestion (single, header "Analysis Feedback"):
|
|
177
|
+
- **Go deeper** (recommended) — deep-dive the lowest-confidence dimension
|
|
178
|
+
- **Adjust direction** — change focus or raise a specific question
|
|
179
|
+
- **Supplement information** — user has additional context/constraints/corrections
|
|
180
|
+
- **Analysis complete** — sufficient, exit to scoring
|
|
181
|
+
|
|
182
|
+
Question text: `Round {N} | Confidence: {overall}% | Weakest: {weakest_dim} ({dim_score}%)`
|
|
183
|
+
|
|
184
|
+
**3.4 Handle response** (always record choice + impact to the report discussion area):
|
|
185
|
+
|
|
186
|
+
| Choice | Action |
|
|
187
|
+
|------|------|
|
|
188
|
+
| Go deeper | AskUserQuestion sub-direction → CLI/agent exploration → merge findings |
|
|
189
|
+
| Adjust direction | capture new direction → new exploration → record Decision (old vs new, reason, impact) |
|
|
190
|
+
| Supplement information | capture input → integrate → CLI-verify when needed → record correction |
|
|
191
|
+
| Analysis complete | exit → record convergence reason |
|
|
192
|
+
|
|
193
|
+
Go-deeper sub-direction: AskUserQuestion (single, "Deep-dive direction", up to 4: 3 from unresolved questions/low-confidence findings/unexplored dimensions + 1 heuristic "examine from a different angle").
|
|
194
|
+
|
|
195
|
+
**3.5 Update discussion area**: append Round N (input, direction, Q&A, corrections, new insights); append Technical Solutions (this round's proposed/validated/rejected); replace Current Understanding block; update TOC.
|
|
196
|
+
|
|
197
|
+
**3.6 Round Narrative Synthesis** (appended each round):
|
|
198
|
+
```markdown
|
|
199
|
+
### Round N: Narrative Synthesis
|
|
200
|
+
**Starting point**: Building on the previous round's [conclusions/questions], this round enters from [starting point].
|
|
201
|
+
**Key progress**: [New findings] [confirmed/refuted/modified] the prior understanding about [hypothesis].
|
|
202
|
+
**Decision impact**: User chose [feedback type], causing the analysis direction to be [adjusted/deepened/maintained].
|
|
203
|
+
**Current understanding**: After this round, the core understanding updates to [updated understanding].
|
|
204
|
+
**Remaining questions**: [remaining questions driving next round]
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
**3.7 Intent Drift** (Round ≥ 2): per item ✅/🔄/⚠️ implicitly absorbed pending confirmation/❌ not discussed. ❌ or ⚠️ → proactively raise with the user at the start of the next round.
|
|
208
|
+
|
|
209
|
+
**3.8 Re-score confidence** (each round): show delta `Confidence: {prev}% → {current}% ({±N%}), {weakest_dim} still needs deepening`.
|
|
210
|
+
|
|
211
|
+
**3.9 Quality mechanisms**:
|
|
212
|
+
- **Pressure Pass** (mandatory ≥1 before Step 4): highest-confidence finding → pressure gradient (evidence demand → assumption probe → boundary/tradeoff → root cause check). Record under `#### Pressure Test`.
|
|
213
|
+
- **Devil's Advocate**: a dimension > 0.7 → challenge "what if [finding] doesn't hold?" (once per dimension)
|
|
214
|
+
- **Scope Minimizer**: findings > 5 and scope expanding → "minimal viable conclusion set?"
|
|
215
|
+
- **Stall Detection**: 2 consecutive rounds delta < 5% → "analysis may be stalling, suggest switching direction or converging"
|
|
216
|
+
|
|
217
|
+
**3.10 Pre-convergence Readiness Gate** (on "Analysis complete"): blocking conditions — an ❌ with no deferral exists | any dimension < 40% | no pressure pass | unresolved contradiction | overall < 80%. If blocked, AskUserQuestion: supplement then continue / ignore risk and continue (record `residual_risks[]` and the accepted confidence).
|
|
218
|
+
|
|
219
|
+
**Auto (-y)**: auto deep-dive ≤3 rounds, readiness gate auto-overridden and residual risk recorded.
|
|
220
|
+
|
|
221
|
+
### Step 4: Six-Dimension Scoring
|
|
222
|
+
|
|
223
|
+
Synthesizing all exploration, discussion, and feedback, score six dimensions:
|
|
224
|
+
|
|
225
|
+
| Dimension | Focus | Score |
|
|
226
|
+
|------|------|----|
|
|
227
|
+
| Feasibility | technical difficulty, team capability, time, tooling | 1-5 |
|
|
228
|
+
| Impact | user value, business value, tech-debt reduction, DX | 1-5 |
|
|
229
|
+
| Risk | failure modes, security, scalability, regression | 1-5 |
|
|
230
|
+
| Complexity | integration points, dependencies, learning curve, testing | 1-5 |
|
|
231
|
+
| Dependencies | external services, internal modules, data, infrastructure | 1-5 |
|
|
232
|
+
| Alternatives | 2+ other approaches and their trade-offs | N/A |
|
|
233
|
+
|
|
234
|
+
Each dimension cites specific evidence (code ref, exploration data point) and marks a per-dimension confidence %. Construct a probability-impact risk matrix. Form a Go/No-Go/Conditional recommendation and overall confidence %. Write the confidence summary (each dimension's score + overall + pressure pass result + residual risks) into the report conclusion area.
|
|
235
|
+
|
|
236
|
+
### Step 5: Synthesis & Conclusion
|
|
237
|
+
|
|
238
|
+
**5.1 Intent Coverage check** (mandatory before synthesis):
|
|
239
|
+
```markdown
|
|
240
|
+
### Intent Coverage Matrix
|
|
241
|
+
| # | Original Intent | Status | Where Addressed | Notes |
|
|
242
|
+
|---|----------------|--------|-----------------|-------|
|
|
243
|
+
| 1 | [intent] | ✅ Addressed | Round N, Conclusion #M | |
|
|
244
|
+
| 2 | [intent] | 🔀 Transformed | Round N → M | Original: X → Final: Y |
|
|
245
|
+
| 3 | [intent] | ❌ Missed | — | Reason |
|
|
246
|
+
```
|
|
247
|
+
Gate: each ❌ Missed item must either (a) get an added round or (b) be user-confirmed defer.
|
|
248
|
+
|
|
249
|
+
**5.2 Synthesize insights**: compile the Decision Trail, key conclusions with evidence + confidence, recommendations with rationale + priority + actionable steps (**merge validated `technical_solutions[]` into high-priority recommendations**), open questions and follow-up suggestions → write into `outputs/findings.json`.
|
|
250
|
+
|
|
251
|
+
**5.3 Write findings.json** (artifact paths and metadata are declared in `prepare/analyze.md` contract):
|
|
252
|
+
```json
|
|
253
|
+
{
|
|
254
|
+
"mode": "macro|micro|quick|gaps",
|
|
255
|
+
"topic": "",
|
|
256
|
+
"dimensions": [],
|
|
257
|
+
"findings": [],
|
|
258
|
+
"decisions": [],
|
|
259
|
+
"architecture_template_evidence": null,
|
|
260
|
+
"scope_verdict": "small|medium|large",
|
|
261
|
+
"recommendation": "go|go_with_conditions|no_go"
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
**5.4 Write risk-matrix.json**:
|
|
266
|
+
```json
|
|
267
|
+
{ "risks": [], "assumptions": [], "open_questions": [] }
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
**5.4b Session priors.** Use `wiki_context` to find Wiki candidates and `wiki_reference` to open the entries used in analysis. On completion, Evolve seals the exact bodies and bound constraints as `session-priors`, with their lookup scope and source search. Keep separate architecture-template evidence in `findings.json#architecture_template_evidence`.
|
|
271
|
+
|
|
272
|
+
**5.5 report conclusion area**: conclusion summary, ranked conclusions, prioritized recommendations; Current Understanding (Final); Decision Trail (key decisions, direction-change timeline, trade-offs); Intent Coverage Matrix; session stats.
|
|
273
|
+
|
|
274
|
+
**5.6 Interactive recommendation review** (auto skips): AskUserQuestion (up to 4 at a time, by priority): confirm → accepted / modify → modified / delete → rejected. Write back each recommendation's `review_status` to findings.json.
|
|
275
|
+
|
|
276
|
+
### Step 6: Decision Extraction
|
|
277
|
+
|
|
278
|
+
**Always executed** — in full mode after synthesis, in quick mode as the main step.
|
|
279
|
+
|
|
280
|
+
**6.1 Identify gray areas**: analyze goal + loaded context, find undecided implementation areas. Domain-aware generation:
|
|
281
|
+
- what the user will SEE: layout, density, interaction, states
|
|
282
|
+
- what the user will CALL: responses, errors, auth, versioning
|
|
283
|
+
- what the user will RUN: output format, flags, modes, error handling
|
|
284
|
+
- what the user will READ: structure, tone, depth, flow
|
|
285
|
+
- how it is ORGANIZED: standards, grouping, naming, exceptions
|
|
286
|
+
|
|
287
|
+
Generate 3-5 **phase-specific** gray areas. Skip upstream already-decided areas; if upstream is locked: focus on SHOULD/MAY and gaps.
|
|
288
|
+
|
|
289
|
+
**6.2 Gray area selection** (`-y` skips): AskUserQuestion to let the user pick which areas to discuss (including "All areas"/"Skip"). Choosing Skip → write empty Locked/Free/Deferred, proceed to 6.5.
|
|
290
|
+
|
|
291
|
+
**6.3 Deep-dive discussion**: multiple rounds of dialogue per selected area (3-4 questions/area), give Option A/B/C with trade-offs, record each decision per the Decision Recording Protocol. **Scope guardrail**: roadmap phase boundaries are fixed, discuss HOW not WHETHER; user raises a new capability → "assign it to its own phase, record first" → into Deferred.
|
|
292
|
+
|
|
293
|
+
**6.4 Classify decisions**:
|
|
294
|
+
- **Locked**: hard decisions unchangeable during implementation
|
|
295
|
+
- **Free**: implementer's discretion
|
|
296
|
+
- **Deferred**: pushed to a later phase
|
|
297
|
+
|
|
298
|
+
If `researchContext` exists: append a research-backed suggestion for each Free area.
|
|
299
|
+
|
|
300
|
+
Write the classification into `findings.json#decisions[]`, each item marked `{title, class: locked|free|deferred, context, options[], chosen, reason}`.
|
|
301
|
+
|
|
302
|
+
**6.5 Deferred → issue**: for each Deferred decision, create an issue in `.workflow/issues/issues.jsonl`: `status: deferred, priority: 5, severity: low, source: analyze, tags: [deferred, analyze]`. Require user confirmation (or `-y` flag) before writing to external stores.
|
|
303
|
+
|
|
304
|
+
### Wrap-up
|
|
305
|
+
|
|
306
|
+
Write the single `report.md`, with the following frontmatter and fixed sections:
|
|
307
|
+
|
|
308
|
+
```md
|
|
309
|
+
---
|
|
310
|
+
verdict: ready
|
|
311
|
+
summary: one-line summary of the analysis conclusion
|
|
312
|
+
constraints: []
|
|
313
|
+
decisions: []
|
|
314
|
+
concerns: []
|
|
315
|
+
next:
|
|
316
|
+
- { command: ew-plan, reason: analysis ready, needs: [current-analysis] }
|
|
317
|
+
---
|
|
318
|
+
## Summary
|
|
319
|
+
## Conclusion/Verdict
|
|
320
|
+
## Discussion/Retrospective
|
|
321
|
+
## Artifacts
|
|
322
|
+
## Handoff/Next
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
In macro mode, if `scope_verdict == large`, next points to roadmap instead of plan. In the report, reference domain values with `{{aref:current-analysis#/...}}` or an aref block, **never copy the JSON source of truth**.
|
|
326
|
+
|
|
327
|
+
→ Wrap-up (archiving, spec/knowhow extraction) follows ref/finish-work.md.
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## Decision Recording Protocol
|
|
332
|
+
|
|
333
|
+
Record as it occurs:
|
|
334
|
+
|
|
335
|
+
| Trigger | Record |
|
|
336
|
+
|------|------|
|
|
337
|
+
| Direction choice | what was chosen, why, what was discarded |
|
|
338
|
+
| Key finding | content, impact scope, confidence, effect on assumptions |
|
|
339
|
+
| Assumption change | old → new understanding, reason, impact |
|
|
340
|
+
| User feedback | input, rationale for adopting/adjusting |
|
|
341
|
+
| Disagreement/trade-off | conflicting views, trade-off basis, final choice |
|
|
342
|
+
| Scope adjustment | before/after scope, triggering reason |
|
|
343
|
+
| Technical solution proposed/validated/rejected | solution, rationale, alternatives, status |
|
|
344
|
+
|
|
345
|
+
**Decision Record format**:
|
|
346
|
+
```
|
|
347
|
+
> **Decision**: [Description]
|
|
348
|
+
> - **Context**: [Trigger]
|
|
349
|
+
> - **Options considered**: [Alternatives]
|
|
350
|
+
> - **Chosen**: [Approach] — **Reason**: [Rationale]
|
|
351
|
+
> - **Rejected**: [Why discarded]
|
|
352
|
+
> - **Evidence Source**: [cli-explore-agent | CLI delegate | user input | code anchor] — REQUIRED, manual Read/Grep alone is INVALID
|
|
353
|
+
> - **Impact**: [effect on the analysis]
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
**Technical Solution format**:
|
|
357
|
+
```
|
|
358
|
+
> **Solution**: [approach/pattern/implementation]
|
|
359
|
+
> - **Status**: [Proposed / Validated / Rejected]
|
|
360
|
+
> - **Problem**: [what it solves]
|
|
361
|
+
> - **Rationale**: [why this path]
|
|
362
|
+
> - **Alternatives**: [other options and why discarded]
|
|
363
|
+
> - **Evidence**: [file:line or code anchor]
|
|
364
|
+
> - **Next Action**: [follow-up or none]
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
## Success Criteria
|
|
368
|
+
|
|
369
|
+
- [ ] Scope determined (small/medium/large) from codebase analysis
|
|
370
|
+
- [ ] CLI exploration completed with concrete evidence
|
|
371
|
+
- [ ] Interactive discussion rounds reached consensus or max rounds
|
|
372
|
+
- [ ] Six-dimension scoring completed with evidence citations
|
|
373
|
+
- [ ] Intent coverage matrix shows no unhandled ❌
|
|
374
|
+
- [ ] Decision extraction captured all locked/free/deferred decisions
|
|
375
|
+
- [ ] findings.json written with all scored dimensions
|
|
376
|
+
|
|
377
|
+
---
|
|
378
|
+
|
|
379
|
+
## Domain Invariants
|
|
380
|
+
|
|
381
|
+
- Every one of the six dimension scores must cite exploration/CLI evidence; manual Read/Grep is invalid.
|
|
382
|
+
- Pressure pass is mandatory ≥1 time before synthesis.
|
|
383
|
+
- Intent Coverage must have no unhandled ❌ before wrap-up.
|
|
384
|
+
- `-q` only skips exploration and scoring; decision extraction cannot be omitted.
|
|
385
|
+
- `--gaps` goes issue root-cause analysis; a root cause cannot be confirmed without evidence.
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## Error Codes
|
|
390
|
+
|
|
391
|
+
| Code | Condition | Recovery |
|
|
392
|
+
|------|-----------|----------|
|
|
393
|
+
| E001 | No relevant findings | Broaden the search or ask the user to clarify |
|
|
394
|
+
| W001 | cli-explore-agent failed | Retry once; if still failing mark subsequent decisions LOW CONFIDENCE, continue with existing context |
|
|
395
|
+
| W002 | CLI timeout | Shorten prompt and retry; if still failing mark that perspective [LOW CONFIDENCE] and continue |
|
|
396
|
+
| W003 | Max rounds reached (5) | Force synthesis, offer a continue option |
|
|
397
|
+
|
|
398
|
+
## Knowledge Hooks
|
|
399
|
+
|
|
400
|
+
- Open the Wiki and working Memory entries you use through the Run MCP tools. CLI-only hosts can record exact reads in the Run knowledge receipt with `--reads` and `--from-search`.
|
|
401
|
+
- Write domain terms and accepted decisions to `report.md` frontmatter (`decisions`/`constraints`); sealing stages them as spec candidates automatically.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-brainstorm
|
|
3
|
+
description: Explore a problem space and produce bounded options for the Evolve chain
|
|
4
|
+
argument-hint: '<intent> [--from <artifact-alias>] [-y]'
|
|
5
|
+
wiki_categories: [arch, learning]
|
|
6
|
+
search_profile:
|
|
7
|
+
wiki: references
|
|
8
|
+
memory: optional
|
|
9
|
+
session-mode: run
|
|
10
|
+
contract:
|
|
11
|
+
consumes: []
|
|
12
|
+
produces:
|
|
13
|
+
- path: outputs/brainstorm.json
|
|
14
|
+
kind: brainstorm
|
|
15
|
+
alias: current-brainstorm
|
|
16
|
+
role: primary
|
|
17
|
+
required: true
|
|
18
|
+
schema: brainstorm/1.0
|
|
19
|
+
contract_version: 2.1
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
# Brainstorm
|
|
23
|
+
|
|
24
|
+
Brainstorm is a planning step inside the Evolve Skill. Explore the problem space, record assumptions and alternatives, and leave a bounded option set for the next chain step.
|
|
25
|
+
|
|
26
|
+
1. Read the current Session objective, boundary contract and available Wiki evidence. Search `agent-memory context "<intent keywords>" --category arch --include-memory` when prior decisions or learning examples may affect the options.
|
|
27
|
+
2. Separate observed facts, user constraints, open questions and proposed options.
|
|
28
|
+
3. Compare options against scope, risk, reversibility and verification cost.
|
|
29
|
+
4. Write `outputs/brainstorm.json` with source evidence for every material conclusion.
|
|
30
|
+
5. Propose a follow-up chain only when the option requires a typed artifact or a durable decision.
|
|
31
|
+
|
|
32
|
+
Do not implement changes in this step. Do not replace the Session chain with an untracked recommendation.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-companion
|
|
3
|
+
description: Execute and verify one bounded task in an Evolve Run.
|
|
4
|
+
session-mode: run
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Companion
|
|
8
|
+
|
|
9
|
+
Read the bound task, resolve applicable Agent Memory context, perform the scoped change and run the direct verification. Record the command and observed result in the Run summary. When the task needs a plan or separate review, send the coordinator the evidence and revised scope so it can update the pending chain.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-execute
|
|
3
|
+
wiki_categories: [coding]
|
|
4
|
+
search_profile:
|
|
5
|
+
wiki: [constraints, references]
|
|
6
|
+
memory: [error, correction, verified_fix]
|
|
7
|
+
description: Implement code changes following the DAG and waves of current-plan, producing implementation results and a local smoke self-check
|
|
8
|
+
argument-hint: '[scope] [-y] [--task TASK-ID] [--method agent|cli|auto] [--executor <tool>] [--auto-commit]'
|
|
9
|
+
contract:
|
|
10
|
+
consumes:
|
|
11
|
+
- kind: plan
|
|
12
|
+
alias: current-plan
|
|
13
|
+
required: false
|
|
14
|
+
schema: plan/1.0
|
|
15
|
+
role: primary
|
|
16
|
+
- kind: review-findings
|
|
17
|
+
alias: latest-review
|
|
18
|
+
required: false
|
|
19
|
+
schema: review-findings/1.0
|
|
20
|
+
role: primary
|
|
21
|
+
- kind: fix-directions
|
|
22
|
+
alias: latest-fix-directions
|
|
23
|
+
required: false
|
|
24
|
+
schema: fix-directions/1.0
|
|
25
|
+
role: attachment
|
|
26
|
+
- kind: diagnosis
|
|
27
|
+
alias: latest-debug
|
|
28
|
+
required: false
|
|
29
|
+
schema: diagnosis/1.0
|
|
30
|
+
role: primary
|
|
31
|
+
- kind: priors
|
|
32
|
+
alias: session-priors
|
|
33
|
+
required: false
|
|
34
|
+
schema: priors/1.0
|
|
35
|
+
role: evidence
|
|
36
|
+
produces:
|
|
37
|
+
- path: outputs/execution.json
|
|
38
|
+
kind: artifact
|
|
39
|
+
alias: current-execution
|
|
40
|
+
role: primary
|
|
41
|
+
required: true
|
|
42
|
+
schema: artifacts/1.0
|
|
43
|
+
- path: outputs/task-results.json
|
|
44
|
+
kind: task-results
|
|
45
|
+
role: attachment
|
|
46
|
+
required: false
|
|
47
|
+
schema: task-results/1.0
|
|
48
|
+
- path: outputs/self-check.json
|
|
49
|
+
kind: self-check
|
|
50
|
+
role: evidence
|
|
51
|
+
required: false
|
|
52
|
+
schema: self-check/1.0
|
|
53
|
+
- path: outputs/change-manifest.json
|
|
54
|
+
kind: change-manifest
|
|
55
|
+
role: evidence
|
|
56
|
+
required: false
|
|
57
|
+
schema: change-manifest/1.0
|
|
58
|
+
gates:
|
|
59
|
+
exit:
|
|
60
|
+
- execution-complete
|
|
61
|
+
- self-check-passed
|
|
62
|
+
contract_version: 2.1
|
|
63
|
+
required_links:
|
|
64
|
+
- references/prepare.md
|
|
65
|
+
- references/workflow.md
|
|
66
|
+
session-mode: run
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
# Execute
|
|
70
|
+
|
|
71
|
+
Read [preparation](references/prepare.md), then follow the [workflow](references/workflow.md).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
refs:
|
|
3
|
+
- path: ref/finish-work.md
|
|
4
|
+
when: Wrapping up
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Pre-task Thinking: execute
|
|
8
|
+
|
|
9
|
+
## Purpose
|
|
10
|
+
|
|
11
|
+
The output of execute is "an implementation consistent with the real diff + traceable per-task evidence," not "it looks like it ran." Think through the execution boundaries and failure handling before you start.
|
|
12
|
+
|
|
13
|
+
## Degradation Routing (no plan)
|
|
14
|
+
|
|
15
|
+
When `current-plan` is absent (entry gate skipped, not failed), execute enters **degradation mode**. Assess the upstream that IS available and route:
|
|
16
|
+
|
|
17
|
+
| Available upstream | Scope | Route |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `latest-review` (review-findings) | ≤3 findings, each ≤2 files | **Companion**: seal this run as `needs-retry` with verdict note "degraded to companion", then use Evolve's internal Companion route with the finding list as intent |
|
|
20
|
+
| `latest-review` (review-findings) | >3 findings or cross-module | **Odyssey planex**: seal this run as `needs-retry`, then `/odyssey-planex` with the review findings as requirement |
|
|
21
|
+
| `latest-debug` (diagnosis + fix-directions) | fix-directions present | **Companion** if ≤2 files; **Odyssey planex** otherwise |
|
|
22
|
+
| No upstream at all | — | **Abort**: report E001 "No plan and no alternative upstream; run plan first" |
|
|
23
|
+
|
|
24
|
+
Degradation close: complete the Run honestly with `evolve run complete <run_id> ... --verdict done_with_concerns --advance --json`(report.md `concerns` 记录 degradation reason 与 target command),或 `evolve run cancel <run_id> ... --json` 后重新派发目标命令。这保留 run 记录而不伪造 plan。(v2 的 `evolve session done <run_id> --verdict needs-retry` 为 deprecated/legacy-only。)
|
|
25
|
+
|
|
26
|
+
**Never fabricate a plan artifact to satisfy the gate.** The degradation path is the compliant escape.
|
|
27
|
+
|
|
28
|
+
## Input Interpretation
|
|
29
|
+
|
|
30
|
+
- When `current-plan` is present, follow the bound Artifact path described in the workflow. Stay within the waves and task scope declared in that plan.
|
|
31
|
+
- A `plan/1.0` artifact with `source_format: pi-markdown` is the approved external-Plan variant: treat `markdown` as the complete authoritative plan body. Derive the execution task order, dependencies, boundaries, risks, and acceptance checks explicitly from that Markdown before dispatch; do not require structured `task_ids` or `wave_ids`, and do not invent work absent from the Markdown.
|
|
32
|
+
- When `current-plan` is absent: follow the Degradation Routing table above. Do NOT proceed to Step 1+ without a plan.
|
|
33
|
+
- How is the execution method decided? `--method` specifies explicitly (agent / cli / auto), or auto-routes by domain (frontend / backend / general each go to their own executor). When the user names a tool, use `--executor` — don't guess.
|
|
34
|
+
- `--task TASK-ID` runs only a single task; without args, execute the full DAG/waves. Already-completed tasks resume from checkpoint and are not re-executed.
|
|
35
|
+
- `-y` auto mode skips all interactive questions (executor choice, inter-wave confirmation, blocked prompts); non-auto mode must stop and ask the user retry / skip / abort when a wave is blocked.
|
|
36
|
+
|
|
37
|
+
## Required Context
|
|
38
|
+
|
|
39
|
+
- With `current-plan`: for a structured Evolve Plan, read waves, dependency graph, collision report, and each task's convergence.criteria. For `source_format: pi-markdown`, use the derived task/dependency view from the authoritative `markdown` body and preserve every stated acceptance check as convergence criteria.
|
|
40
|
+
- Open bound `session-priors` and apply the Wiki rules from the matching scope. When the task adds paths or requires further coding or UI rules, run `wiki_context` for that scope and open any references it adds.
|
|
41
|
+
- Use the architecture document and the sealed plan as implementation context. If a failure or retry needs past examples, search working Memory and open the relevant results.
|
|
42
|
+
|
|
43
|
+
## Boundaries and Invariants
|
|
44
|
+
|
|
45
|
+
### Artifact Compatibility Recovery
|
|
46
|
+
|
|
47
|
+
For an incompatible sealed input, inspect the bound input via `evolve run artifact-read` when the consumer has a Run. Cancel that attempt with the current revision fences, then place a producer step ahead of the pending consumer to publish a compatible artifact. Verify the new publication and dispatch the consumer using `evolve run next` and the current Session revision.
|
|
48
|
+
|
|
49
|
+
Migration must preserve the sealed source bytes and raw registry role/alias semantics. Never repair this boundary with chain skip, Run rebind, direct Artifact Registry edits/rewrites, or source Artifact mutation; semantic republish creates a derived compatibility Artifact and receipt instead.
|
|
50
|
+
|
|
51
|
+
- self-check is only a scoped build/test smoke over this run's changes (narrowest suites covering changed behavior; never a repository-wide matrix), **not** an acceptance conclusion — formal acceptance is in a separate verify run; never overstep to issue a verdict here.
|
|
52
|
+
- Write only source-code changes and this run's domain artifacts; protocol state (run completion, artifact registration) is handled by the CLI — do not manually edit state.
|
|
53
|
+
- After each task completes, do knowledge extraction per trigger conditions: deviations → arch constraints; retry_count ≥ 2 → debug fix mode; design_rationale → learning knowhow.
|
|
54
|
+
- Full knowledge extraction (constraints/decisions/terminology) and archiving go uniformly through `ref/finish-work.md`; execute only does incremental learnings.
|
|
55
|
+
- When a task carries `issue_id`, sync the issue status after completion (all task_refs done → resolved, any failure → in_progress); in non-auto mode, confirm before writing back.
|
|
56
|
+
|
|
57
|
+
## Risk Checklist
|
|
58
|
+
|
|
59
|
+
- Are there write conflicts within the same wave? Follow task deps and the collision report — only parallelize tasks with no write conflict; conflicting ones go to different waves.
|
|
60
|
+
- Does each task have real evidence? Files changed, commands/tests executed, and per-criterion pass/fail must all be recorded; do not mark done based on the executor's self-report alone.
|
|
61
|
+
- Has a single task exhausted 3 chances? Normal execution → focused retry → degraded execution; still failing records blocked and writes a checkpoint. Never fabricate completion.
|
|
62
|
+
- What about downstream of a blocked task? Propagate blocked along dependencies; downstream tasks with unmet dependencies are marked `upstream_blocked` — don't pretend they can run.
|
|
63
|
+
- Are changes out of bounds? Write only source-code changes and this run's domain artifacts; protocol state (run completion, artifact registration) is handled by the CLI — do not manually edit state.
|
|
64
|
+
- Are tech-stack constraints followed? The specs' allowed_languages / disallowed_imports must be scanned once after changes; a hit is critical.
|
|
65
|
+
|
|
66
|
+
## Gate Intent
|
|
67
|
+
|
|
68
|
+
- `execution-complete`: every task in the plan reaches a terminal state (done / blocked with checkpoint); `execution.json` is written and completed tasks carry a summary + status.
|
|
69
|
+
- `self-check-passed`: the gate fails only when the scoped build/test smoke over this run's changes was not run this round or an unhandled critical tech-stack violation (allowed_languages / disallowed_imports) remains. A self-check result of `gaps_found` does **not** block run completion — gaps are recorded as concerns in the report for the separate verify run to consume (formal acceptance lives in verify, not here).
|