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,163 @@
|
|
|
1
|
+
# Evolve 知识路由
|
|
2
|
+
|
|
3
|
+
本文件是 Evolve 内部唯一的知识路由。Wiki、Session/Skill 收尾沉淀、候选审查和发布共用 Agent Memory 与统一 Wiki。`workflow-closeout` 只作为旧调用名的兼容入口,并引用本文件。
|
|
4
|
+
|
|
5
|
+
## 路由边界
|
|
6
|
+
|
|
7
|
+
| 用户意图 | 路由 | 默认状态 | 主要入口 |
|
|
8
|
+
| --- | --- | --- | --- |
|
|
9
|
+
| 查约束、查参考、查术语、查 Wiki | `read` | 只读 | `agent-memory wiki constraints|references|reference|search|get` |
|
|
10
|
+
| Session 或 Skill 完成后的沉淀 | `closeout` | 生成候选 | `agent-memory closeout session|skill|scan|show` |
|
|
11
|
+
| 审查重复、重叠、冲突和证据 | `review` | 只读 | `closeout show`、`wiki get`、`wiki search` |
|
|
12
|
+
| 发布或更新候选 | `publish` | 需要明确授权 | `wiki propose` → `wiki apply` 或 `closeout publish` |
|
|
13
|
+
| 迁移旧 Spec 和 Knowhow | `migrate` | 预览 | `agent-memory wiki migrate` |
|
|
14
|
+
| 发现可归因于 Skill 的问题 | `evolve` | 只读回溯 | `agent-memory session review` 或 `agent-memory evolve review`,随后转交 `workflow-evolve` |
|
|
15
|
+
| 候选需要新 Skill 或新流程包 | `skill-design` | 只读决策 | `agent-memory closeout route`,满足结构条件时显式调用元 Skill 设计 |
|
|
16
|
+
|
|
17
|
+
### 导入现有 Spec 和 Knowhow
|
|
18
|
+
|
|
19
|
+
在原项目根目录运行 `evolve knowledge import` 查看迁移条目和待审查数,追加 `--apply` 后写入该项目的 Agent Memory Wiki。也可以用 `evolve knowledge import "<项目路径>" --apply` 从其他目录执行。用 `--root "<目标项目路径>"` 指定不同目标,用 `--project <来源 ID>` 沿用已使用的迁移身份。
|
|
20
|
+
|
|
21
|
+
只迁移 Knowhow 时,在项目或全局导入命令中加 `--knowhow-only`,例如 `evolve knowledge import "<项目路径>" --knowhow-only`。核对预览后用相同参数加 `--apply`。底层命令 `agent-memory wiki migrate` 也支持该选项。
|
|
22
|
+
|
|
23
|
+
`evolve knowledge import --global --apply` 将用户目录 `.maestro` 中的知识导入独立的 `~/.evolve` Wiki,用 `agent-memory --root "<用户目录>/.evolve" context "<查询>"` 查阅。重复导入保留已存在的相同条目,原始 Markdown 保留为出处。
|
|
24
|
+
|
|
25
|
+
### 统一 Wiki 条目
|
|
26
|
+
|
|
27
|
+
正式知识只进入 Wiki 条目。原 Spec 和 Knowhow 通过属性表达差异。
|
|
28
|
+
|
|
29
|
+
- `mode: constraint` 表示执行约束、质量门禁和适用规则。
|
|
30
|
+
- `mode: reference` 表示经验、方法、模板、术语和可选建议。
|
|
31
|
+
- `status: active|needs_review|deprecated` 表示生命周期。
|
|
32
|
+
- `scope` 默认用 `project`,也可用 `task:<kind>` 或 `path:<glob>` 限定适用范围。
|
|
33
|
+
- `categories`、`tags` 和 `keywords` 用于查询和路由,不能替代 `mode` 与 `scope`。
|
|
34
|
+
- `sources` 必须能回查到完成回执、消息锚点或迁移来源。
|
|
35
|
+
|
|
36
|
+
不再创建或直接修改 `.workflow/specs/`、`.workflow/knowhow/`。旧目录只作为迁移输入和历史档案。
|
|
37
|
+
|
|
38
|
+
## 路由规则
|
|
39
|
+
|
|
40
|
+
1. 先识别操作,再识别目标。`查、搜索、读取、引用` 进入 `read`,`收尾、沉淀、harvest` 进入 `closeout`,`审查、重复、冲突、候选` 进入 `review`,`发布、批准、应用` 进入 `publish`,`迁移、导入` 进入 `migrate`。
|
|
41
|
+
2. 只有明确要求发布或应用时才执行写入。检索结果、Closeout 候选、审计结果和回溯信号都只是证据。
|
|
42
|
+
3. Session 收尾和独立 Skill 收尾进入同一 Closeout 流程。使用完成回执中的证据范围,不从未授权的工作区文本补证。
|
|
43
|
+
4. Closeout 提取出可复用方法后,先核对适用条件、验证证据和现有条目的关系,再决定追加来源、创建候选、更新条目或标记冲突。
|
|
44
|
+
5. 同一内容在唯一活跃 `reference` 条目中重复验证时,可以只追加 `sources`。正文、作用域和模式变化必须走 Wiki 提案。
|
|
45
|
+
6. `constraint` 与 `reference` 发生冲突时保留双方证据,创建待审查关系,不自动覆盖活跃条目。
|
|
46
|
+
7. 没有合格候选、候选被拒绝或用户延期都属于正常结果,不得为了填充知识库而制造条目。
|
|
47
|
+
8. 发现信号能定位到具体 Skill、版本、读取文件和证据时,才转交 `workflow-evolve`。项目级规则和跨任务经验留在 Wiki。
|
|
48
|
+
9. 候选只有在需要新契约、新产物、跨 Skill 路由、至少 3 个稳定步骤或明确要求新增 Skill 时,才进入 `skill-design`。单条指令和条件链接继续由 `workflow-evolve` 处理。
|
|
49
|
+
|
|
50
|
+
## 操作流程
|
|
51
|
+
|
|
52
|
+
### `read`
|
|
53
|
+
|
|
54
|
+
按查询类型选择最窄的入口。约束读取必须带适用上下文,参考读取保留条目 ID 和来源。
|
|
55
|
+
|
|
56
|
+
旧条目可以继续通过 `wiki get <entry-id>` 查阅。只有旧 `skill:` 作用域的条目需要经 Wiki 提案确认新的适用范围,才会进入上下文。混合作用域的条目沿用其项目、任务和路径条件。
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
agent-memory --root <project> wiki constraints --category <category>
|
|
60
|
+
agent-memory --root <project> wiki references "<topic>" --task <kind>
|
|
61
|
+
agent-memory --root <project> wiki reference <entry-id> --task <kind>
|
|
62
|
+
agent-memory --root <project> wiki search "<query>"
|
|
63
|
+
agent-memory --root <project> wiki get <entry-id>
|
|
64
|
+
agent-memory --root <project> context "<query>" --task <kind> --session <session-id>
|
|
65
|
+
agent-memory --root <project> context "<query>" --task <kind> --session <session-id> --include-memory
|
|
66
|
+
agent-memory --root <project> context "<query>" --session <current-session-id> --memory-session <historical-session-id> --include-memory
|
|
67
|
+
agent-memory --root <project> context "<query>" --context-file <context.json> --include-memory
|
|
68
|
+
agent-memory --root <project> search "<query>" --scope memory --scene <scene> --type <type> --reads <knowledge-reads.json>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
没有命中时保留查询条件和空结果。不要把缺少参考误写成新的约束。
|
|
72
|
+
|
|
73
|
+
### Search 与 Get/Query 的 ID 边界
|
|
74
|
+
|
|
75
|
+
- `search(query, filters?)` 用查询词、任务、路径和分类发现候选。按 `knowledge_id` 打开选中的条目。
|
|
76
|
+
- 搜索结果返回稳定的 `knowledge_id`,供后续精确读取和审计使用。
|
|
77
|
+
- `get(id)`、`query({ id })` 和 `reference(id)` 负责单条读取,必须接收稳定 ID。Wiki 可以兼容已登记的 `aliases`,写入操作不接受别名。
|
|
78
|
+
- `constraints(context)` 根据任务、路径和分类解析适用约束。返回结果带 `knowledge_id`,用于 Run 快照和消费记录。
|
|
79
|
+
- `propose`、`changes` 和 `apply` 属于变更接口,必须使用规范化条目 ID、候选 ID 或变更 ID,并校验基线哈希。
|
|
80
|
+
|
|
81
|
+
标准调用顺序是 `search → get/query`。搜索只返回摘要和 ID,精确读取才返回完整正文、作用域和来源。
|
|
82
|
+
|
|
83
|
+
### 搜索回执
|
|
84
|
+
|
|
85
|
+
Run MCP 的 `wiki_context` 和 `wiki_reference` 自动记录 `knowledge_reads/1.0`,封存时写入回执。分析 Run 也会封存已读取的 Wiki 正文和约束为 `session-priors`。后续 Run 实际打开该工件后,回执中的 `priors_reuse` 记录产物 ID、哈希和原 Run ID。
|
|
86
|
+
|
|
87
|
+
- `searches[]` 记录查询词、阶段过滤条件、返回 ID 和命中数,不接收条目 ID。
|
|
88
|
+
- `reads[]` 记录 `wiki reference <id>`、`wiki get <id>` 或 `memory get <id>` 的精确读取,必须带稳定 ID。
|
|
89
|
+
- `reads[].from_search_id` 将精确读取关联到对应搜索。已有的 CLI 历史回执还可使用 `priors` 来源标记。
|
|
90
|
+
- 跨 CLI 调用时使用同一个 `--reads` 文件,精确读取再传 `--from-search <search-id>`,保持同一份回执中的搜索与读取关联。`--trace-file` 仍作为兼容别名。
|
|
91
|
+
- `content_sha256` 和 `version` 用于确认读取内容与回执时点一致。
|
|
92
|
+
- 没有执行搜索时不生成伪造记录。零命中使用 `returned_ids: []` 保留为可分析信号。
|
|
93
|
+
|
|
94
|
+
### L3 初始化与无侵入回溯
|
|
95
|
+
|
|
96
|
+
初始化时调用 `agent-memory context` 加载 L3 Wiki 约束和参考,返回 `agent-memory-envelope/1.0`。宿主保留自己的 system prompt、模型调用和工具链,初始化过程不读取宿主历史文件。
|
|
97
|
+
|
|
98
|
+
`context --session` 只标记当前工作上下文。需要限定历史 Working Memory 时显式使用 `--memory-session`,避免把新 Session ID 错当成历史记忆过滤条件。
|
|
99
|
+
|
|
100
|
+
任务结束后使用已提交的 Session/Run 回执执行 Review 和自进化。原始 CLI 历史不是常规输入。未来如果需要补充历史,按 `host_kind` 和显式配置的历史根目录选择性读取,并把结果转换成现有 `transcript-evidence/1.0`,只服务于一次明确的回溯请求。
|
|
101
|
+
|
|
102
|
+
### `closeout`
|
|
103
|
+
|
|
104
|
+
先消费已提交回执,再读取候选。模型提取使用 Agent Memory 的统一系统提示词,候选保留来源消息 ID 和回执身份。
|
|
105
|
+
|
|
106
|
+
```text
|
|
107
|
+
agent-memory --root <project> closeout session <session-id> --project <source-project-id> --receipt <receipt-id>
|
|
108
|
+
agent-memory --root <project> closeout skill <execution-id> --skill <skill-id> --skill-version <version> --status <status> --transcript <messages.json> --project <source-project-id>
|
|
109
|
+
agent-memory --root <project> closeout scan <source-project-root> --project <source-project-id>
|
|
110
|
+
agent-memory --root <project> closeout show <receipt-id> --project <source-project-id>
|
|
111
|
+
agent-memory --root <project> closeout route <closeout-id> <candidate-id> --skill <skill-id> --skill-version <version>
|
|
112
|
+
agent-memory --root <project> skill-design run <task-id> --runner <meta-skill-runner.mjs>
|
|
113
|
+
agent-memory --root <project> skill-design review <design-id>
|
|
114
|
+
agent-memory --root <project> skill-design replay <design-id> --runner <host-runner.mjs> --scenarios <cases.json>
|
|
115
|
+
agent-memory --root <project> skill-design apply <design-id>
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
重复投递按回执身份幂等处理。模型失败后使用同一回执重试,不重新构造证据。Closeout 自身和 `workflow-evolve` 的执行记录不进入自动沉淀,避免递归。
|
|
119
|
+
|
|
120
|
+
### `review`
|
|
121
|
+
|
|
122
|
+
审查时逐项核对以下内容。
|
|
123
|
+
|
|
124
|
+
- 候选是否有适用条件、动作和验证结果。
|
|
125
|
+
- 每个来源 ID 是否属于本次回执的冻结证据。
|
|
126
|
+
- 候选是否与活跃条目相同、重叠、冲突或仅仅相关。
|
|
127
|
+
- `mode`、`scope`、`categories` 和 `sources` 是否完整。
|
|
128
|
+
- 是否应追加来源、创建 Wiki 提案、等待补证或保持零候选。
|
|
129
|
+
|
|
130
|
+
审查输出保留候选 ID、条目 ID、关系、证据和建议动作。审查本身不应用文件变更。
|
|
131
|
+
|
|
132
|
+
`closeout route` 对 `route=skill-design` 生成当前项目 `.agent-memory/skill-design/tasks/` 下的设计任务。设计任务必须带目标 Skill,避免生成无法回放的无主候选。`skill-design run` 通过显式元 Skill runner 生成设计回执,`review` 校验候选能从目标基线重建,`replay` 复用现有 Skill replay,`apply` 和 `rollback` 复用现有版本应用链。路由结果中的 `invoke_meta_skill` 只表示允许显式调用,不代表自动启动元 Skill。
|
|
133
|
+
|
|
134
|
+
### `publish`
|
|
135
|
+
|
|
136
|
+
新条目或正文变化先创建提案,再在明确授权后应用。
|
|
137
|
+
|
|
138
|
+
```text
|
|
139
|
+
agent-memory --root <project> wiki propose <change.json> --closeout <closeout-id> --candidate <candidate-id>
|
|
140
|
+
agent-memory --root <project> wiki changes --entry <entry-id>
|
|
141
|
+
agent-memory --root <project> wiki apply <change-id>
|
|
142
|
+
agent-memory --root <project> closeout publish <closeout-id> <candidate-id> "<title>"
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
应用前核对目标条目基线、证据和作用域。应用后重建 Wiki 索引并读取结果验证。基线漂移、证据缺失、关系未裁决或授权不明确时保持候选待处理。
|
|
146
|
+
|
|
147
|
+
### `migrate`
|
|
148
|
+
|
|
149
|
+
迁移先预览,再逐范围核对。旧 Spec 映射为 `mode: constraint`,旧 Knowhow 映射为 `mode: reference`。保留原 ID、来源文件、旧标签和别名。无法判断作用域、身份冲突或引用断链时使用 `status: needs_review`。
|
|
150
|
+
|
|
151
|
+
```text
|
|
152
|
+
agent-memory --root <project> wiki migrate <legacy-root> --project <source-project-id> --scope project
|
|
153
|
+
agent-memory --root <project> wiki migrate <legacy-root> --project <source-project-id> --scope project --apply
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
迁移重复执行必须命中同一稳定 ID。应用前保留来源快照和迁移映射,应用后核对旧查询与新 Wiki 的有效条目集合。
|
|
157
|
+
|
|
158
|
+
## 与其他 Skill 的关系
|
|
159
|
+
|
|
160
|
+
- 当前 Agent Memory 主包负责识别意图并读取本路由。
|
|
161
|
+
- `workflow-closeout` 只提供旧名称兼容,不维护第二份知识规则。
|
|
162
|
+
- `workflow-evolve` 只处理有证据归因到 Skill 行为的修改、回放、应用和回滚。
|
|
163
|
+
- `ew-odyssey`、`team-swarm` 和 `ew-skill-design` 可以产生证据或候选,但知识落点仍由本路由决定。
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Evolve Session execution and recovery
|
|
2
|
+
|
|
3
|
+
Use the bundled evolve command. A checkout can invoke the same entry with node dist/workflow-cli.js. Session and Run state, requests and sealed artifact bytes share the SQLite database under .agent-memory/. Working outputs and campaign checkpoints live under the run_dir returned by the controller.
|
|
4
|
+
|
|
5
|
+
## Start and dispatch
|
|
6
|
+
|
|
7
|
+
1. Run `evolve install` to choose a project or user installation and select Skill packages. For unattended project setup, use `evolve install --scope project --yes`. Commit the project Skill files so Runs can pin them. Use `evolve workflows` to list the packaged Markdown and `evolve workflows show session-run` to open this guide. Use `evolve skills validate <command>` to validate a step's committed contract and required links.
|
|
8
|
+
2. Open with evolve session open "<objective>" --id <session> --actor <actor>. Supply --definition-of-done and --chain "ew-analyze,ew-plan,ew-execute,ew-review" for an argument-free chain. For step arguments, use evolve session chain insert --session <session> --step-id <id> --command <command> --arg "<argument>" --actor <actor> --expected-orchestration-revision <revision>. Add --decision-ref <id> where a step requires a coordinator decision. Pass argument values beginning with a hyphen as --arg=VALUE.
|
|
9
|
+
3. Dispatch evolve run next --session <session> --actor <actor> --expected-orchestration-revision <revision>. The response supplies the exact Run, frozen task, Skill reference, input artifacts and exit gates. Pass these identifiers to the host worker.
|
|
10
|
+
4. Use the returned orchestration_revision for the next Session mutation. Run completion and recovery also take the current Run revision. Supply a stable --request-id for a retry after an uncertain response. Each Session records the normalized mutation payload and the original result. Refresh status after a revision conflict.
|
|
11
|
+
|
|
12
|
+
## Read and execute
|
|
13
|
+
|
|
14
|
+
Open the entry with evolve run skill-read <run> --session <session>. Open each applicable Markdown link with evolve run skill-read <run> <destination> --from <source> --session <session>. Paths are relative to the bound Skill package. If Git objects are unavailable, restore that revision before resuming.
|
|
15
|
+
|
|
16
|
+
Read input artifacts with evolve run artifact-read <run> <alias-or-id> --session <session>. This returns the sealed bytes and lineage from the Run's input binding. Write the outputs declared by the Skill to its run_dir. Use _meta in JSON, the first record of NDJSON, or YAML frontmatter in Markdown. Match the declared kind, schema, role and alias.
|
|
17
|
+
|
|
18
|
+
Use Run MCP `wiki_context` with a keyword for project knowledge. It records the search and returns applicable constraints and candidate reference IDs. Open the references you use with `wiki_reference`. The Run records the originating search ID and exact body hash. Analysis seals those bodies and bound constraints as `session-priors`.
|
|
19
|
+
|
|
20
|
+
For a later Run, open the bound `session-priors` with `read_artifact` before searching again. Use the entries matching its current Wiki scope. Supply the current `scope` with task, paths, categories or repository when it is known. Scope changes call for a fresh lookup. The consumer receipt records the opened artifact, digest and producer Run. CLI artifact reads take the same scope as a JSON object via `--scope`.
|
|
21
|
+
|
|
22
|
+
Hosts can connect to `evolve mcp --root <project> --session <session> --run <run>` for Skill, artifact, Wiki and working Memory reads. CLI-only runs can use `agent-memory context "<topic>" --session <session> --include-memory --reads "<run_dir>/knowledge-reads.json"` and pass the same file with the matching `--from-search` for exact reads. Select one source for direct knowledge reads per Run.
|
|
23
|
+
|
|
24
|
+
For a bound Codex worker, use `evolve delegate "<prompt>" --to codex --mode analysis --session <session> --run <run>`. This connects Codex to that Run’s MCP tools. Use write mode for authorized edits. A host may also execute the step directly or use its own collaboration tools. Use `evolve delegate` without a Run binding for a second opinion from Agy.
|
|
25
|
+
|
|
26
|
+
## Verify and continue
|
|
27
|
+
|
|
28
|
+
Seal directly with `evolve run complete <run> --session <session> --actor <actor> --expected-orchestration-revision <revision> --expected-run-revision <revision> --summary "<observed result>"`. Repeat `--gate <id>` for each verified exit gate. Completion validates required reads, evidence and outputs, then seals and advances the step in one transaction. Use `run check` for diagnostics. Record qualified outcomes with `--verdict done_with_concerns`.
|
|
29
|
+
|
|
30
|
+
Follow continuation.action. For decide, run evolve run decide <decision-id> --session <session> --actor <actor> --expected-orchestration-revision <revision> --verdict proceed|fix|escalate --summary "<decision evidence>". For next, allocate the pending step. For complete, use evolve session complete --session <session> --actor <actor> --expected-orchestration-revision <revision>. Review and harvest completed evidence through the [knowledge route](knowledge-route.md).
|
|
31
|
+
|
|
32
|
+
## Recover
|
|
33
|
+
|
|
34
|
+
Read evolve session status --session <session> and evolve run brief <run> --session <session>. Resume the exact bound Run and any domain checkpoint in its run_dir. For a blocked Run, transition it to running when the blocker clears. For a failed attempt, use evolve run transition <run> failed --session <session> --actor <actor> --expected-orchestration-revision <revision> --expected-run-revision <revision> --reason "<evidence>". Cancellation uses evolve run cancel with the same fences and reason. Allocate the resulting pending step through run next. New attempts retain retry lineage and bind the current Git version.
|
|
35
|
+
|
|
36
|
+
Historical Session receipts are available to agent-memory session review and agent-memory closeout session. Start an Evolve Session for new execution and reference the historical evidence in its objective when relevant.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-orchestrate
|
|
3
|
+
description: Intent-to-chain planner over the canonical Session/Run lifecycle
|
|
4
|
+
argument-hint: "<intent> [-y] [-c] [--amend]"
|
|
5
|
+
contract:
|
|
6
|
+
refs:
|
|
7
|
+
- path: ew-orchestrate.md
|
|
8
|
+
goal: true
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# Prepare: Evolve
|
|
12
|
+
|
|
13
|
+
Evolve 是意图到链的规划器。本文件定义 **公共接口**、**分类协议**、**建链协议** 和 **分解协议**。
|
|
14
|
+
需要分类时查阅[意图分类目录](ew-orchestrate.md),需要分派或恢复时查阅[执行循环](orchestrator-run-loop.md)。
|
|
15
|
+
|
|
16
|
+
## Public Flags
|
|
17
|
+
|
|
18
|
+
| Flag | 行为 |
|
|
19
|
+
|------|------|
|
|
20
|
+
| `-y` | 自动确认低风险分类和 proposal;不越高风险、低置信度、边界歧义、drift 熔断 |
|
|
21
|
+
| `-c` | 继续唯一 live compatible Session(`evolve-session/1.0`);多候选必须询问;有 open decision gate 时进入 audited recovery |
|
|
22
|
+
| `--amend` | 修改唯一 live Session 的目标;剩余文本为 change request |
|
|
23
|
+
|
|
24
|
+
其余文本全部视为 intent。Platform、roadmap、quality、模板复用、并行与对抗策略由 intent、Session state、Skill contract 和 host runtime 推断。
|
|
25
|
+
|
|
26
|
+
## Classification Protocol(A_CLASSIFY)
|
|
27
|
+
|
|
28
|
+
读取 deferred `workflows/ew-orchestrate.md`,执行意图分类:
|
|
29
|
+
|
|
30
|
+
1. **Exact match**:`continue/next/go/继续` → state_continue
|
|
31
|
+
2. **Semantic match**:LLM 语义理解匹配 task_type(见意图分类目录)
|
|
32
|
+
3. **Selection priorities**:issue_id > team > UI/design > multi-step > single-step > companion fallback
|
|
33
|
+
4. **State validation(W003)**:execute 无 plan → 警告并前置 plan;test 未执行 → 警告并前置 execute
|
|
34
|
+
5. **Classification evidence(必须)**:记录匹配了哪个 pattern、排除了哪些备选、confidence level。无记录的分类不可进入 A_CREATE
|
|
35
|
+
|
|
36
|
+
输出:`{ task_type, scope, issue_id, phase_ref, urgency }`
|
|
37
|
+
|
|
38
|
+
## Chain Creation Protocol(A_CREATE)
|
|
39
|
+
|
|
40
|
+
### 1. Specs 预检
|
|
41
|
+
|
|
42
|
+
建链前通过 Agent Memory 读取适用的 Wiki 约束,并记录搜索及精确读取。
|
|
43
|
+
|
|
44
|
+
### 2. Skill 名预校验
|
|
45
|
+
|
|
46
|
+
通过 evolve skills 列出内置步骤,并用 evolve skills validate <command> 核对目标项目提交中的步骤契约。
|
|
47
|
+
|
|
48
|
+
### 3. 组装 chain 定义
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"intent": "<intent>",
|
|
53
|
+
"engine": "coordinator",
|
|
54
|
+
"quality_mode": "standard",
|
|
55
|
+
"auto_mode": false,
|
|
56
|
+
"boundary_contract": {
|
|
57
|
+
"in_scope": [], "out_of_scope": [], "constraints": [], "definition_of_done": ""
|
|
58
|
+
},
|
|
59
|
+
"steps": [
|
|
60
|
+
{ "command": "ew-analyze", "args": "--session {session}", "stage": "analyze", "goal_ref": "G1", "retry_max": 2 },
|
|
61
|
+
{ "command": "ew-execute", "args": "--session {session}", "stage": "execute", "goal_ref": "G1", "retry_max": 2 },
|
|
62
|
+
{ "command": "ew-review", "args": "--session {session}", "stage": "review", "retry_max": 2 }
|
|
63
|
+
],
|
|
64
|
+
"decision_points": [],
|
|
65
|
+
"decomposition": {
|
|
66
|
+
"execution_criteria": [],
|
|
67
|
+
"goals": [
|
|
68
|
+
{ "id": "G1", "goal": "...", "done_when": "...", "lifecycle": ["execute", "review"], "status": "pending" }
|
|
69
|
+
],
|
|
70
|
+
"changelog": []
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- `engine: coordinator` 是兼容持久化字段,不是 Session 类型或策略
|
|
76
|
+
- `{session}` `{intent}` 占位符由运行时替换
|
|
77
|
+
- `decision_points` 只为读取/继续 legacy Session 保留;新链使用可执行 Skill step
|
|
78
|
+
|
|
79
|
+
### 4. 创建
|
|
80
|
+
|
|
81
|
+
`evolve session open "{intent}" --id ew-{slug} [--definition-of-done "<text>"] [--chain <argument-free commands...>] --participant {actor_id} --actor {actor_id} --request-id {open_request_id} --reason "<reason>" [--evidence <ref> ...] --json`
|
|
82
|
+
|
|
83
|
+
chain 可随 `session open --chain` 建入无参数 steps;带 domain args 的 step 随后必须用 fenced `session chain insert --arg` 写入,使用与 actor 相同的 participant、fresh request ID 和 open receipt 返回的 exact `orchestration_revision`。无临时 chain-file。随后进入共享执行循环(orchestrator-run-loop.md)。
|
|
84
|
+
|
|
85
|
+
## Decomposition Protocol(A_DECOMPOSE)
|
|
86
|
+
|
|
87
|
+
设 `decomposition_owner = "ew-orchestrate"`。下游步骤读取确认后的任务边界。
|
|
88
|
+
|
|
89
|
+
1. 分类意图广度:narrow / 单步 / {init} 链 → 跳过分解
|
|
90
|
+
2. broad/medium → 最多问 3 轮:Scope / Constraints / Definition of Done(`-y` 不跳过广泛歧义)
|
|
91
|
+
3. 派生 `execution_criteria` + `goals`(每个含 `done_when` + `evidence` + `lifecycle`)
|
|
92
|
+
4. `boundary_contract` 随 `session open` 建入;goals 装入 chain 的 `decomposition` 元数据
|
|
93
|
+
5. 需要终结目标审计时,追加 audit/verify Skill step(拥有 Run,可按 contract 产出 proposal)
|
|
94
|
+
|
|
95
|
+
### Goal 绑定提示
|
|
96
|
+
|
|
97
|
+
分解完成后输出 `/goal` 绑定提示词(不阻塞):
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
📋 任务分解完成。可随时设定目标:
|
|
101
|
+
/goal 完成以游子目标:
|
|
102
|
+
- G1: {goal} — 完成条件: {done_when}
|
|
103
|
+
- G2: ...
|
|
104
|
+
达成条件: session.json 中 goals[*].status == "done" 且 chain[*].status ∈ {completed,skipped}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Minimum Chain Rules
|
|
108
|
+
|
|
109
|
+
| 意图证据 | 初始链 |
|
|
110
|
+
|---------|--------|
|
|
111
|
+
| 窄修复/变更 | analyze → plan → execute → review/test(按需) |
|
|
112
|
+
| 广泛重写/迁移 | analyze-macro → scope decision → plan/roadmap |
|
|
113
|
+
| 头脑风暴/探索 | brainstorm → 仅 Skill-proposed continuation |
|
|
114
|
+
| 压力测试/grill | grill → 仅 Skill-proposed continuation |
|
|
115
|
+
| 正式规格 | blueprint → plan |
|
|
116
|
+
| 已有 compatible Session | 不重建;进入共享循环 |
|
|
117
|
+
|
|
118
|
+
Roadmap 仅在多 release 证据时推断。Quality 基于 specs 和可观测风险,非用户 flag。
|
|
119
|
+
|
|
120
|
+
## resolvePhase 优先级
|
|
121
|
+
|
|
122
|
+
1. `intent_analysis.phase_ref`(结构化提取)
|
|
123
|
+
2. 正则匹配 "phase N" 或裸数字
|
|
124
|
+
3. 项目状态推断:in-progress execute → 首个未完成 phase → 最新 artifact phase
|
|
125
|
+
4. `analyze-plan-execute` 链 → null(用 `{run_dir}`)
|
|
126
|
+
5. 所有命令均 phase-independent → null
|
|
127
|
+
6. 询问用户
|
|
128
|
+
|
|
129
|
+
## Invariants(Evolve 特有)
|
|
130
|
+
|
|
131
|
+
1. **One chain, executor-neutral** — 执行始终派发 run-executor(默认行为),不产生 Session 分型
|
|
132
|
+
2. **Session before execution** — session.json 经 `session open --chain` 创建后才执行(`orchestration_revision` CAS 保护所有 mutation)
|
|
133
|
+
3. **Creator owns decomposition** — Evolve 创建 boundary_contract + goals;后续 orchestrator 只消费不覆盖
|
|
134
|
+
4. **Classification evidence** — 分类必须留痕(匹配 pattern、排除备选、confidence)
|
|
135
|
+
5. **Verdict 驱动链推进** — 由 fenced `evolve run complete ... --advance --verdict done|done_with_concerns` 驱动 chain step 完成;链终结后 `session complete`
|
|
136
|
+
6. **禁止以上游文消耗为由中断执行** — harness 自动处理 context compression
|
|
137
|
+
7. **控制权优先级** — Evolve 拥有 initial chain 选择 + proposal disposition;Skill 拥有领域判断;Runtime 独占 mutation authority
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ew-analyze
|
|
3
|
+
wiki_categories: [arch]
|
|
4
|
+
search_profile:
|
|
5
|
+
wiki: [constraints, references]
|
|
6
|
+
memory: [correction, error, verified_fix]
|
|
7
|
+
description: Perform multi-dimensional analysis of a topic or existing implementation, producing findings and a risk-matrix consumable by plan
|
|
8
|
+
argument-hint: '[topic] [-y] [-q] [--from <artifact-alias>] [--gaps [ISS-ID]]'
|
|
9
|
+
required_links:
|
|
10
|
+
- references/prepare.md
|
|
11
|
+
- references/workflow.md
|
|
12
|
+
contract:
|
|
13
|
+
consumes:
|
|
14
|
+
- kind: guidance
|
|
15
|
+
alias: current-guidance
|
|
16
|
+
required: false
|
|
17
|
+
schema: guidance/1.0
|
|
18
|
+
role: primary
|
|
19
|
+
- kind: blueprint
|
|
20
|
+
alias: current-blueprint
|
|
21
|
+
required: false
|
|
22
|
+
schema: blueprint/1.0
|
|
23
|
+
role: primary
|
|
24
|
+
- kind: diagnosis
|
|
25
|
+
alias: latest-debug
|
|
26
|
+
required: false
|
|
27
|
+
schema: diagnosis/1.0
|
|
28
|
+
role: primary
|
|
29
|
+
produces:
|
|
30
|
+
- path: outputs/findings.json
|
|
31
|
+
kind: findings
|
|
32
|
+
alias: current-analysis
|
|
33
|
+
role: primary
|
|
34
|
+
required: true
|
|
35
|
+
schema: findings/1.0
|
|
36
|
+
- path: outputs/risk-matrix.json
|
|
37
|
+
kind: risk-matrix
|
|
38
|
+
role: evidence
|
|
39
|
+
required: false
|
|
40
|
+
schema: risk-matrix/1.0
|
|
41
|
+
- path: outputs/priors.json
|
|
42
|
+
kind: priors
|
|
43
|
+
alias: session-priors
|
|
44
|
+
role: evidence
|
|
45
|
+
required: false
|
|
46
|
+
schema: priors/1.0
|
|
47
|
+
gates:
|
|
48
|
+
exit:
|
|
49
|
+
- exploration-done
|
|
50
|
+
- discussion-round
|
|
51
|
+
- scoring-complete
|
|
52
|
+
- intent-covered
|
|
53
|
+
contract_version: 2.1
|
|
54
|
+
session-mode: run
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
# Analyze
|
|
58
|
+
|
|
59
|
+
Read [preparation](references/prepare.md), then follow the [analysis workflow](references/workflow.md).
|
|
60
|
+
|
|
61
|
+
- Read [boundary review](references/boundary-grill.md) when a responsibility conflict is found.
|
|
62
|
+
- Read [issue gap analysis](references/issue-gaps-analyze.md) for the --gaps branch.
|
|
@@ -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,59 @@
|
|
|
1
|
+
# Issue Gaps Analysis — Root-Cause Protocol
|
|
2
|
+
|
|
3
|
+
Root-cause analysis for registered issues, triggered by `analyze --gaps [ISS-ID]`. Supports single issue (`ISS-ID`) or batch (all open/registered) with classification and parallel analysis. Produces `analysis` enrichment on each issue record plus a `context.md` for downstream `plan --gaps`.
|
|
4
|
+
|
|
5
|
+
## Input
|
|
6
|
+
|
|
7
|
+
- `ISS-ID` (optional): specific issue to analyze. If omitted, analyze all `open` / `registered` issues.
|
|
8
|
+
- `DEPTH`: `standard` or `deep` (default `standard`).
|
|
9
|
+
|
|
10
|
+
## Pipeline
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
Load Issues → Classify & Group → Gather Context (per group) → Parallel Analysis → Write issue.analysis → Output context.md
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
### 1. Load issues
|
|
17
|
+
|
|
18
|
+
- `ISS-ID` given: load that single issue from the issue registry; fatal if missing (`E_ISSUE_NOT_FOUND`). Skip classification, go straight to context gathering.
|
|
19
|
+
- No `ISS-ID`: load all issues where `status ∈ {open, registered}`; fatal if none (`E_NO_ISSUES`).
|
|
20
|
+
|
|
21
|
+
### 2. Classify & group (batch mode only)
|
|
22
|
+
|
|
23
|
+
Group issues by affected area so co-located issues share one exploration pass:
|
|
24
|
+
|
|
25
|
+
- Same location prefix (first 2 path segments) → same group.
|
|
26
|
+
- Shared `affected_components` → same group.
|
|
27
|
+
- Remaining ungrouped → individual groups (1 issue each).
|
|
28
|
+
|
|
29
|
+
Each group: `{ group_id, label, issues[], shared_context_keywords[] }`. Display the breakdown (skip on `-y`).
|
|
30
|
+
|
|
31
|
+
### 3. Gather codebase context (per group)
|
|
32
|
+
|
|
33
|
+
Merge and deduplicate keywords from every issue in the group (title, description, location, affected_components).
|
|
34
|
+
|
|
35
|
+
- **standard**: `agent-memory code search` per group; grep fallback flags the analysis `[LOW CONFIDENCE]` (semantic depth lost).
|
|
36
|
+
- **deep**: `agent-memory code search` multi-prompt + semantic Agent search (error handling, data flow, deps), merged.
|
|
37
|
+
|
|
38
|
+
Build `GROUP_CONTEXT`: related files, key snippets (≤50 lines), dependency chain.
|
|
39
|
+
|
|
40
|
+
### 4. Run analysis (per group, parallel across groups) — mandatory, not substitutable by manual Read/Grep
|
|
41
|
+
|
|
42
|
+
Dispatch analysis per group via Agent (or `evolve delegate --role analyze --mode analysis`). For each issue: identify root cause (`file:line`) → assess impact → list related files → rate confidence → suggest fix direction, noting cross-issue relationships within the group.
|
|
43
|
+
|
|
44
|
+
Expected per issue: `{ iss_id, root_cause, impact, related_files[], confidence, suggested_approach, cross_refs[] }`. Evidence-only, no speculation.
|
|
45
|
+
|
|
46
|
+
If delegate fails (timeout / unavailable / parse error), fall back to Agent with the same prompt, set `confidence=low`, flag `[LOW CONFIDENCE]`, and record `{ tool: "agent-fallback", reason }`.
|
|
47
|
+
|
|
48
|
+
### 5. Write issue analysis
|
|
49
|
+
|
|
50
|
+
For each analyzed issue, set `issue.analysis = { root_cause, affected_files, impact_scope, fix_direction, confidence, cross_refs, analyzed_at, tool, depth }`, update `updated_at`, and append a `{ action: "analyzed" }` history entry. Status is unchanged — analysis is metadata enrichment. Re-read the registry to confirm the field is present.
|
|
51
|
+
|
|
52
|
+
### 6. Output context.md
|
|
53
|
+
|
|
54
|
+
Aggregate all analyzed issues into `context.md`, organized by group: per-issue root cause, affected files, impact scope, fix direction, confidence, cross-refs; a Cross-Group Dependencies section; and a Constraints section split into **Locked** (derived from root-cause evidence) and **Free** (implementation choices left to the planner).
|
|
55
|
+
|
|
56
|
+
## Output
|
|
57
|
+
|
|
58
|
+
- Issue registry: each analyzed record enriched with an `analysis` field.
|
|
59
|
+
- `context.md`: grouped root-cause summary consumed by `plan --gaps`.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Pre-task Thinking: analyze
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
The output of analysis is "a trustworthy judgment for downstream plan," not a pretty report. Shape the goal clearly before you start.
|
|
6
|
+
|
|
7
|
+
- What is the core question this analysis must answer? How does the user's original User Intent break down into decidable sub-items?
|
|
8
|
+
|
|
9
|
+
## Input Interpretation
|
|
10
|
+
|
|
11
|
+
- Is the input a **topic text** (macro, exploring impact surface) or **pure numbers** (micro, milestone-level deep dive)? Only pure numbers take the micro path; treat mixed input as text.
|
|
12
|
+
- Is there a `--from` upstream artifact? If so, the alias in `consumes` is injected by create — skip locked decisions directly and prioritize analyzing open decisions. Do not overturn already-locked upstream conclusions.
|
|
13
|
+
- `-q` quick: only do decision extraction, skip exploration and six-dimensional scoring — but **decision extraction cannot be omitted**.
|
|
14
|
+
- `--gaps`: switch to issue root-cause analysis, giving symptom/root-cause evidence/impact surface/fix direction per issue. Root cause cannot be confirmed without evidence.
|
|
15
|
+
|
|
16
|
+
## Required Context
|
|
17
|
+
|
|
18
|
+
- With `current-guidance` / `current-blueprint`: read locked constraints as fixed boundaries for the analysis; open questions as discussion seeds.
|
|
19
|
+
- With `latest-debug`: treat the diagnosis conclusion as a known symptom; the analysis focuses on impact surface and fix direction rather than re-locating the bug.
|
|
20
|
+
- Project specs (arch category) and domain glossary: keep terminology consistent; new term candidates go into the report rather than scattered.
|
|
21
|
+
|
|
22
|
+
## Boundaries and Invariants
|
|
23
|
+
|
|
24
|
+
- Analysis produces judgment only — it does not modify source or pre-resolve downstream plan tasks.
|
|
25
|
+
- Already-locked upstream conclusions are inviolable; the analysis prioritizes open decisions.
|
|
26
|
+
- The scope judgment (small/medium/large) determines whether downstream is roadmap or plan: large = 3+ independent subsystems or hard serial dependencies.
|
|
27
|
+
|
|
28
|
+
## Risk Checklist
|
|
29
|
+
|
|
30
|
+
- Are evidence sources independent? Each dimension of the six-dimensional scoring must cite output from cli-explore-agent or CLI delegate; **manual Read/Grep does not count as independent evidence**.
|
|
31
|
+
- Has at least 1 pressure pass been run? High-confidence findings must withstand the pressure gradient of evidence demand → assumption probe → boundary/tradeoff → root cause.
|
|
32
|
+
- Are there any ❌ uncovered Intent items? Uncovered items must either get another round or be confirmed deferred by the user — do not converge with defects.
|
|
33
|
+
- Has the discussion stalled? Two consecutive rounds with delta < 5% should switch angles or converge — don't spin uselessly up to the 5-round limit.
|
|
34
|
+
- Is the scope judgment (small/medium/large) grounded? large = 3+ independent subsystems or hard serial dependencies; this directly determines whether downstream is roadmap or plan.
|
|
35
|
+
|
|
36
|
+
## Gate Intent
|
|
37
|
+
|
|
38
|
+
- `exploration-done`: the exploration phase produces ≥1 code anchor and ≥1 CLI perspective is complete before entering discussion.
|
|
39
|
+
- `discussion-round`: at least 1 round of interaction with user feedback + 1 confidence re-evaluation before entering scoring.
|
|
40
|
+
- `scoring-complete`: all six dimensions scored with each dimension cited, before synthesis.
|
|
41
|
+
- `intent-covered`: the Intent Coverage Matrix has no unhandled ❌ before wrapping up.
|
|
42
|
+
- The quick / gaps branches only keep decision-extraction-related gates; exploration/scoring gates automatically do not apply.
|