maestro-flow 0.5.41 → 0.5.43

package/workflows/odyssey-base-codex.md

@@ -1,47 +1,47 @@
-# Odyssey 共享基座 (Codex)
+# Odyssey Shared Base (Codex)
 
-所有 Odyssey 命令（debug, improve, planex, review-test-fix, ui）共享此基座。
+Shared by all Odyssey commands (debug, improve, planex, review-test-fix, ui).
 
 <execution_discipline>
-**四条铁律：**
 
-1. **Phase auto-commit** — 每个阶段完成后自动 `git commit`，无需用户确认
-   - 代码变更 + understanding.md → `git add` → `git commit -m "{command}({slug}): {phase} — {摘要}"`
-   - session.json / evidence.ndjson 为运行时状态，不纳入 commit
+1. **Phase auto-commit** — auto `git commit` after each phase
+   - Code changes + understanding.md → `git add` → `git commit -m "{command}({slug}): {phase} — {summary}"`
+   - session.json / evidence.ndjson are runtime state, excluded from commits
 
-2. **Confident edits only, but must attempt** — 有把握才改代码；仅在真正需要人类判断时记录 decision
+2. **Confident edits only, but must attempt** — edit when confident; record decision only when human judgment truly needed
    - Confident → edit + commit
-   - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`，不动代码
-   - ⚠️ **Decision gate** — 仅以下情形算 decision：跨模块架构权衡需人类方向 | 业务语义歧义修复可能改变意图 | 需引入新依赖或 breaking API
-   - ❌ "不确定怎么修"、"范围太大"、"历史遗留" 不是合法 decision 理由
+   - Needs decision → `evidence.ndjson {"phase":"decision","status":"pending"}`, no code change
+   - **Decision gate** — only these qualify: cross-module architecture tradeoffs needing human direction | business semantics ambiguity where fix may change intent | new dependency or breaking API required
+   - "Unsure how to fix", "Too large scope", "Pre-existing issue" are NOT valid decision reasons
 
-3. **多 CLI 辅助** — `maestro delegate` 多角度交叉验证
-   - 不同阶段用不同 `--role`（analyze / review / explore）
-   - **`--role` fallback:** 当 `cli-tools.json` 的 `roles` 为空时，`--role` 自动 fallback 到首个启用工具。效果等同于 `--to <first-enabled>`，但保留语义标注便于日志追踪
-   - 所有 delegate 调用 `run_in_background: true`，等回调继续
+3. **Multi-CLI assist** — `maestro delegate` for cross-angle verification
+   - Different `--role` per phase (analyze / review / explore)
+   - **`--role` fallback:** when `cli-tools.json` `roles` is empty, `--role` auto-falls back to first enabled tool. Equivalent to `--to <first-enabled>` but preserves semantic annotation for log tracking
+   - All delegate calls `run_in_background: true`, wait for callback
 
-4. **禁止以上下文消耗为由中断** — harness 自动 context compression；以"上下文不足"或"已执行 N 阶段"为由中断属纪律违反，必须完整走到 S_RECORD → END
+4. **Never abort for context exhaustion** — harness auto-compresses context; aborting due to "insufficient context" or "already ran N phases" is a discipline violation. Must complete through S_RECORD → END.
 
-**Zero-residual:** 每个发现必须有 action（fix / issue / decision）。"仅报告"和"历史遗留跳过"均禁止。
+**Zero-residual:** Every finding must have an action (fix / issue / decision). "Report only" and "pre-existing skip" are forbidden.
 </execution_discipline>
 
 <flag_semantics>
-### `--auto` vs `-y` 语义区分
 
-| Flag | 控制范围 | 效果 |
-|------|---------|------|
-| `--auto` | **CLI delegate 调用** | 跳过 delegate 启动前的确认提示，直接 `run_in_background` 执行 |
-| `-y` | **人类决策点** | 所有 `request_user_input` 调用自动选择默认选项，记录为 `deferred` |
+### `--auto` vs `-y`
 
-- `--auto` 不影响人类决策点（ambiguity、triage、goal audit 等仍需确认或 `-y`）
-- `-y` 不影响 delegate 调用（delegate 始终自动执行，`--auto` 仅控制启动前确认提示）
-- 两者可组合使用：`--auto -y` = 全自动模式
-- `session.json.flags` 映射: `auto` ↔ `--auto`, `auto_confirm` ↔ `-y`
+| Flag | Scope | Effect |
+|------|-------|--------|
+| `--auto` | **CLI delegate calls** | Skip delegate launch confirmation, execute `run_in_background` directly |
+| `-y` | **Human decision points** | All `request_user_input` calls auto-select default, record as `deferred` |
+
+- `--auto` does not affect human decision points (ambiguity, triage, goal audit still need confirmation or `-y`)
+- `-y` does not affect delegate calls (delegates always auto-execute, `--auto` only controls pre-launch confirmation)
+- Combine: `--auto -y` = fully automatic mode
+- `session.json.flags` mapping: `auto` ↔ `--auto`, `auto_confirm` ↔ `-y`
 </flag_semantics>
 
 <shared_schemas>
 
-### session.json 标准字段（所有命令共有）
+### session.json standard fields
 
 ```json
 {
@@ -55,18 +55,18 @@
 }
 ```
 
-各命令在此基础上添加特有字段（如 `issue`, `target`, `requirement` 等）。
-**注意:** `cross_phase_loops` 和 `max_loops` 是共有字段，各命令不应在 unique fields 中重复声明。
+Each command adds its own fields (e.g. `issue`, `target`, `requirement`).
+Note: `cross_phase_loops` and `max_loops` are shared fields — commands should not redeclare them.
 
-### evidence.ndjson 基础 schema（每行共有字段）
+### evidence.ndjson base schema
 
 ```json
 {"ts":"","phase":"","type":"","source":"","content":"","note":""}
 ```
 
-各命令定义 phase-specific 扩展字段（如 `hypothesis`, `severity`, `dimension` 等）。
+Each command defines phase-specific extension fields (e.g. `hypothesis`, `severity`, `dimension`).
 
-### patterns[] schema（A_GENERALIZE 输出）
+### patterns[] schema (A_GENERALIZE output)
 
 ```json
 {
@@ -81,15 +81,15 @@
 }
 ```
 
-`source` 字段名统一为 `source`，值由各命令语义决定：
+`source` field value per command:
 
-| Command | source 值 | 含义 |
-|---------|----------|------|
-| debug | root_cause | 根因修复 |
-| improve | diagnosis | 诊断发现 |
-| review-test-fix | finding | 审查发现 |
-| ui | finding | 审查/发散发现 |
-| planex | implementation | 实现模式 |
+| Command | source value | Meaning |
+|---------|-------------|---------|
+| debug | root_cause | Root cause fix |
+| improve | diagnosis | Diagnosed finding |
+| review-test-fix | finding | Review finding |
+| ui | finding | Audit/diverge finding |
+| planex | implementation | Implementation pattern |
 
 ### generalization_stats schema
 
@@ -105,9 +105,8 @@
 </shared_schemas>
 
 <anti_stall>
-**防停滞机制**
 
-### session.json 新增字段
+### progress_metrics fields
 
 ```json
 {
@@ -123,12 +122,12 @@
 
 ### Progress Tracking
 
-每个分析阶段结束时：
-1. 统计 `new_findings`（去重后新发现）和 `repeated`（与已有 evidence 重复）
-2. 写入 `progress_metrics.phase_stats[state_name]`
-3. `new == 0` → `stale_count++`，`convergence_trend = "stalling"`
-4. `new > 0` → `stale_count = 0`，更新 `last_productive_phase`
-5. 连续 2 阶段 new 递减 → `convergence_trend = "diminishing"`
+After each analytical phase:
+1. Count `new_findings` (deduplicated) and `repeated` (matching existing evidence)
+2. Write to `progress_metrics.phase_stats[state_name]`
+3. `new == 0` → `stale_count++`, `convergence_trend = "stalling"`
+4. `new > 0` → `stale_count = 0`, update `last_productive_phase`
+5. 2 consecutive phases with declining new → `convergence_trend = "diminishing"`
 
 ### Direction Diversity
 
@@ -136,45 +135,46 @@
 {
   "phase": "S_DIAGNOSE", "round": 1,
   "strategy_type": "scope_widen|perspective_shift|tool_switch|structural_pivot",
-  "strategy_desc": "扩展搜索到 utils/", "result": "2 new findings"
+  "strategy_desc": "expand search to utils/", "result": "2 new findings"
 }
 ```
 
-**去重规则:** 自迭代前检查同 phase 历史 → 新策略必须在 `strategy_type` 或 `strategy_desc` 上不同 → 4 种 type 均已尝试 → 强制升级 stale_count
+**Dedup rule:** Check same-phase history before self-iteration → new strategy must differ in `strategy_type` or `strategy_desc` → all 4 types tried → force stale_count upgrade
 
 ### Stall Escalation Ladder
 
-| stale_count | 策略 |
-|-------------|------|
-| 0 | 正常推进 |
-| 1 | **换视角** — 不同 CLI 工具、反向追踪、手动阅读。方向必须与 directions_tried 不同 |
-| 2 | **结构性转向** — 重定义搜索维度、换分析框架、拆解子问题。不是参数调优 |
-| 3 | **人工升级** — request_user_input / `-y` 自动 INCONCLUSIVE 并推进 |
+| stale_count | Strategy |
+|-------------|----------|
+| 0 | Normal advance |
+| 1 | **Shift perspective** — different CLI tool, reverse trace, manual read. Must differ from directions_tried |
+| 2 | **Structural pivot** — redefine search dimensions, switch analysis framework, decompose sub-problems. Not parameter tuning |
+| 3 | **Human escalation** — request_user_input / `-y` auto INCONCLUSIVE and advance |
 
-### /loop Heartbeat（可选，`--heartbeat` 启用）
+### /loop Heartbeat (optional, `--heartbeat`)
 
-建议用户 `/loop 270s`。每阶段更新 `session.json.updated_at`。超 15 分钟未更新 → 告警 + stale_count。连续 2 次无更新 → 建议 `-c` resume。
+Suggest `/loop 270s`. Each phase updates `session.json.updated_at`. >15 min without update → alert + stale_count. 2 consecutive no-update → suggest `-c` resume.
 </anti_stall>
 
 <self_iteration>
-**Quality Gate（进度感知版）**
 
-| 维度 | sufficient | insufficient |
-|------|-----------|-------------|
-| Coverage | 已知相关文件/模块均已分析 | 遗漏 grep/git log 可发现的目标 |
-| Depth | ≥80% 发现有 file:line 级证据 | 多数仅泛泛描述 |
-| Actionability | 每条结论有具体后续动作 | 仅"建议关注"类无操作结论 |
+### Quality Gate
+
+| Dimension | Sufficient | Insufficient |
+|-----------|-----------|-------------|
+| Coverage | All known related files/modules analyzed | Missed targets discoverable via grep/git log |
+| Depth | ≥80% findings have file:line evidence | Most findings lack specifics |
+| Actionability | Each conclusion has concrete next action | "Consider reviewing" without action |
 
-**进度感知迭代（替代固定 3 轮）:**
-- phase complete → evaluate 3 dims + check `progress_metrics`
-- any insufficient AND `stale_count < 3` → re-enter，expansion strategy 必须经 directions_tried 去重
-- 按 Stall Escalation Ladder 选择策略类型
+**Progress-aware iteration:**
+- Phase complete → evaluate 3 dimensions + check `progress_metrics`
+- Any insufficient AND `stale_count < 3` → re-enter with expansion strategy (must pass directions_tried dedup)
+- Follow Stall Escalation Ladder for strategy selection
 
 **Expansion strategies:**
-- `scope_widen`: 更多目录、git log 深度 ×2、额外 delegate 角度
-- `perspective_shift`: 不同 CLI 工具、反向追踪、手动阅读
-- `tool_switch`: 切换到未使用的分析工具
-- `structural_pivot`: 重定义问题框架、拆解子问题
+- `scope_widen`: more directories, git log depth ×2, additional delegate angles
+- `perspective_shift`: different CLI tool, reverse trace, manual reading
+- `tool_switch`: switch to unused analysis tool
+- `structural_pivot`: redefine problem framework, decompose sub-problems
 
 **Exit:** all sufficient → advance | `stale_count >= 3` → log gaps, advance
 
@@ -185,111 +185,110 @@
 
 ### A_GENERALIZE
 
-3 层 pattern extraction → 4-agent 并发 scan → cross-layer dedup → iterative deepening。
+3-layer pattern extraction → 4-agent concurrent scan → cross-layer dedup → iterative deepening.
 
-**Pattern 来源:** 由各命令指定（root cause / audit findings / implementation patterns 等）。
+**Pattern source:** specified by each command (root cause / audit findings / implementation patterns).
 
-**3 层提取:**
+**3-layer extraction:**
 
 | Layer | Method | Example |
 |-------|--------|---------|
 | Syntax | Regex → Grep | `eval(`, missing `await`, inline styles |
-| Semantic | Agent 理解反模式 → scan | 未处理异步错误、缺少校验 |
-| Structural | 文件/模块结构相似性 | 同类导入结构、缺少 override |
+| Semantic | Agent understands anti-pattern → scan | Unhandled async errors, missing validation |
+| Structural | File/module structure similarity | Same import structure, missing override |
 
-Write `session.json.patterns[]` — schema 见 `<shared_schemas>` patterns[] 定义。
+Write `session.json.patterns[]` — schema in `<shared_schemas>` patterns[] definition.
 
-**4-agent 并发 scan（spawn_agents_on_csv，wave 号由各命令指定）:**
+**4-agent concurrent scan (spawn_agents_on_csv, wave number specified by each command):**
 
 | Agent | Strategy | Scope |
 |-------|----------|-------|
 | Syntax grep | Grep regex | Full project |
-| Semantic scan | 反模式检查 | Related modules |
-| Structural match | 结构相似文件 | Full project |
+| Semantic scan | Anti-pattern check | Related modules |
+| Structural match | Structurally similar files | Full project |
 | Historical grep | `git log -S` | Git history |
 
-**Cross-layer dedup:** 多层命中 → boost confidence | 单层 → `needs_review` | 历史已修 → `regression_risk`
+**Cross-layer dedup:** multi-layer hit → boost confidence | single-layer → `needs_review` | historically fixed → `regression_risk`
 
-**Iterative deepening:** module ≥3 hits → 定向深扫（max 1 round）
+**Iterative deepening:** module ≥3 hits → targeted deep scan (max 1 round)
 
-**Persist:** understanding.md 泛化 section + `session.json.generalization_stats`（schema 见 shared_schemas）
+**Persist:** understanding.md generalization section + `session.json.generalization_stats`
 
-📌 Auto-commit: `"...({slug}): GENERALIZE — 泛化扫描完成"`
+Commit: `"...({slug}): GENERALIZE — generalization scan complete"`
 
 ### A_DISCOVER
 
-1. **Triage** 每个 hit ±10 行上下文 → 分类 `bug` / `risk` / `safe`
+1. **Triage** each hit ±10 lines context → classify `bug` / `risk` / `safe`
 2. **Route:**
-   - bug + fix_template 可直接应用 → **立即修复** → back to S_FIX
-   - bug + 需跨模块决策或无 fix_template → 创建 issue（含 fix 建议 + 影响分析）
-   - risk → 评估能否直接加 guard；能 → 修
+   - bug + fix_template applicable → immediate fix → back to S_FIX
+   - bug + needs cross-module decision or no fix_template → create issue (with fix suggestion + impact analysis)
+   - risk → assess if guard can be added directly; yes → fix; no → create issue
    - safe → skip
-   Normal: request_user_input | `-y`: auto-fix 有 fix_template 的 bug，其余 create issue
-3. **Cross-phase loops:** `cross_phase_loops++`。`loops >= max_loops` → 必须逐项记录原因（禁止笼统"历史遗留"）
+   Normal: request_user_input | `-y`: auto-fix bugs with fix_template, create issue for rest
+3. **Cross-phase loops:** `cross_phase_loops++`. `loops >= max_loops` → must log per-item reasons (blanket "pre-existing" forbidden)
 4. Append evidence + update understanding.md
 
-📌 Auto-commit: `"...({slug}): DISCOVER — 发现分类完成"`
+Commit: `"...({slug}): DISCOVER — discovery triage complete"`
 
 ### A_RECORD
 
-1. Finalize understanding.md 最后一节 — learnings 按各命令指定的分类表结构化
-   - **两步模式:** 执行中写产出文件（临时）→ 完成后用户通过 next_step_routing 沉淀永久知识
-2. Mark record goal done。Pending decisions: Normal → request_user_input | `-y` → skip (show deferred count)
-3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`。未完成: Normal → request_user_input | `-y` → auto accept
-4. `current_state = "COMPLETED"`，emit completion summary（格式由各命令定义）
+1. Finalize understanding.md final section — learnings structured by each command's category table
+2. Mark record goal done. Pending decisions: Normal → request_user_input | `-y` → skip (show deferred count)
+3. **Goal audit:** all `completion_confirmed` → `phase_goals_all_done = true`. Incomplete: Normal → request_user_input | `-y` → auto accept
+4. `current_state = "COMPLETED"`, emit completion summary (format defined by each command)
 
-📌 Auto-commit: `"...({slug}): RECORD — 会话总结与知识沉淀"`
+Commit: `"...({slug}): RECORD — summary and knowledge persistence"`
 
 </shared_actions>
 
 <shared_appendix>
 
-### Goal Prompt 机制
+### Goal Prompt
 
-**⚠️ 时机守卫：仅 INTAKE 完成后显示一次。RECORD 完成时禁止重显。**
+**Timing guard: display ONCE after INTAKE completes. Never re-display at RECORD.**
 
 ```
-📋 {Command} Odyssey 会话已创建。可随时复制以下 /goal 设定终止条件：
+{Command} Odyssey session created. Copy the /goal below to set termination criteria:
 
-/goal 完成以下目标：
+/goal Complete these goals:
 {for each G in phase_goals where status != "skipped":}
-- {G.id}: {G.goal} — 完成条件: {G.done_when}
+- {G.id}: {G.goal} — done when: {G.done_when}
 {end for}
 {command-specific convergence rules}
-遇到 phase=decision 的 pending 必须 request_user_input，不得自行 resolve。
+Pending phase=decision items must use request_user_input, never self-resolve.
 ```
 
-输出后继续执行不阻塞。
+Continue execution after output, do not block.
 
-### `-y` 通用规则
+### `-y` generic rules
 
 - Decision pending → best-effort continue, record `deferred`
 - 3-strike escalation → auto INCONCLUSIVE
-- Discovery routing → auto-fix 有 fix_template 的 bug，其余 create issue
+- Discovery routing → auto-fix bugs with fix_template, create issue for rest
 - Record pending → skip, show deferred count
 - Record goal audit → auto accept
 
-`deferred` items 在 completion summary 显示为"待决策"；可通过 `-c` 恢复。各命令在自身文件中列出特有 decision points。
+`deferred` items shown in completion summary; recoverable via `-c`. Each command lists its own specific decision points.
 
 ### Phase Goal Lifecycle
 
 `pending → done (confirmed=true)` | `pending → skipped (confirmed=true)` | `pending → failed (confirmed=false)`
 
-`phase_goals_all_done = true` 仅当 ALL goals 有 `completion_confirmed == true`。
+`phase_goals_all_done = true` only when ALL goals have `completion_confirmed == true`.
 
 ### Session Resume (`-c`)
 
-1. `Glob(".workflow/scratch/*-{type}-odyssey-*")` 扫描所有匹配会话目录
-2. **多个会话时，按 `session.json.updated_at` 降序排列，选择最近更新的**
-3. 读取 `session.json` → 显示 summary（issue/target, current_state, phase_goals status）
-4. 跳转到 `current_state` 继续执行
+1. `Glob(".workflow/scratch/*-{type}-odyssey-*")` scan all matching session directories
+2. **Multiple sessions: sort by `session.json.updated_at` descending, select most recent**
+3. Read `session.json` → display summary (issue/target, current_state, phase_goals status)
+4. Jump to `current_state` and continue
 
-### Pre-load（可选，缺失不阻塞）
+### Pre-load (optional, missing does not block)
 
-| 层级 | 命令 |
-|------|------|
+| Layer | Command |
+|-------|---------|
 | Codebase docs | Read `.workflow/codebase/ARCHITECTURE.md` |
-| Wiki search | `maestro search "<keywords>" --json`（top 5） |
+| Wiki search | `maestro search "<keywords>" --json` (top 5) |
 | Specs | `maestro load --type spec --category <cat>` |
 | Role knowledge | `maestro search --category <cat>` → `maestro load --type knowhow --id <id>` |
 | Prior sessions | `Glob(".workflow/scratch/*-{type}-odyssey-*")` |