maestro-flow 0.5.41 → 0.5.43

package/.codex/skills/maestro-ralph-execute/SKILL.md

@@ -8,9 +8,15 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Single-step executor for ralph (adaptive) and maestro (static) sessions.
 Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
 
-Mutual invocation with `$maestro-ralph` forms a self-perpetuating work loop.
+### Notation
 
-**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `ralph-{YYYYMMDD-HHmmss}`（$maestro-ralph 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（$maestro 创建，静态链）。两类都由本 skill 推进；省略 `[session-id]` 时取最新 `status=="running"`。Schema 详见 `$maestro-ralph` 的 Session Schema。
+`Skill(name)` / `Skill(name, args)` = 加载 `~/.codex/skills/{name}/SKILL.md` 或 `.codex/skills/{name}/SKILL.md`（project 覆盖 global），args 填入目标 SKILL.md `<context>` 块的输入参数位。这是 skill 间的内部调用，**不是 CLI 命令**。严禁翻译为 `Bash("maestro {name} {args}")`。
+
+合法 CLI 子命令仅限结构化操作：`maestro ralph next`、`maestro ralph complete`、`maestro ralph retry`、`maestro delegate`、`maestro explore` 等。
+
+Mutual invocation with `Skill(maestro-ralph)` forms a self-perpetuating work loop.
+
+**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `ralph-{YYYYMMDD-HHmmss}`（Skill(maestro-ralph) 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（Skill(maestro) 创建，静态链）。两类都由本 skill 推进；省略 `[session-id]` 时取最新 `status=="running"`。Schema 详见 `Skill(maestro-ralph)` 的 Session Schema。
 </purpose>
 
 <context>
@@ -23,16 +29,18 @@ Remaining  → session_id (if matches maestro-* or ralph-*)
 ```
 Also read `session.auto_mode` from status.json — if true, treat as `-y`.
 
+**session_id requirement:** Once resolved (from args or auto-discovery in A_LOCATE_SESSION), `session_id` MUST be passed to ALL `maestro ralph next|complete|retry` CLI calls via `--session <session_id>`. This prevents accidental cross-session operations when multiple sessions exist.
+
 **Step kinds:**
 
 | Kind | Identifier | Execution | Flow after |
 |------|-----------|-----------|------------|
-| decision step | `step.decision` 非空 | `$maestro-ralph` | Execution ends here |
+| decision step | `step.decision` 非空 | `Skill(maestro-ralph)` | Execution ends here |
 | 执行 step | `step.decision == null` | `Bash("maestro ralph next")` → 内联按其 stdout 执行 → `Bash("maestro ralph complete N --status ...")` | Self-invoke next |
 
 HARD RULES:
 - 执行 step：**统一通过 `maestro ralph next` CLI 加载**。CLI 负责读 command_path（codex SKILL.md）、解析 `<required_reading>` + `<deferred_reading>`、拼接 prompt、写 `step.load.*` + `active_step_index` + `step.status="running"`。不要再在会话里手动 Read + 解析 required_reading
-- decision step：A_EXEC_DECISION 通过 `$maestro-ralph` 直调 handoff 给 ralph 评估（不走 CLI）
+- decision step：A_EXEC_DECISION 通过 `Skill(maestro-ralph)` 直调 handoff 给 ralph 评估（不走 CLI）
 - `command_path` 由 ralph 在 A_BUILD_STEPS 写入 status.json（通过 `maestro ralph skills --platform codex` 预校验；缺失 → ralph next 返回 E006/E007 并拒绝执行）
 - 每个 step 结束必须调用 `maestro ralph complete N --status <S>` 或 `maestro ralph retry N`。STATUS 仅 4 个合法值：`DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`
 - Platform：`session.platform == "codex"`；ralph next CLI 自动按 platform 解析 SKILL.md（无需额外参数）
@@ -48,7 +56,7 @@ HARD RULES:
 7. **status.json 每步骤后由 CLI 原子写盘** — resume-safe
 8. **STATUS 枚举受限** — 仅 `DONE | DONE_WITH_CONCERNS | NEEDS_RETRY | BLOCKED`
 9. **Platform binding** — 仅处理 `session.platform == "codex"` 的会话；platform 缺失视为 codex（向前兼容）
-10. **CLI ≠ Skill** — `maestro ralph next|complete|retry` 是 CLI 子命令（Bash 调用）；`$maestro-ralph` / `$maestro-ralph-execute` 是 skill 直调。**严禁** `Bash("maestro \"intent\"")` 裸 intent 调用，CLI 不接受。
+10. **CLI ≠ Skill** — `maestro ralph next|complete|retry` 是 CLI 子命令（Bash 调用）；`Skill(maestro-ralph)` / `Skill(maestro-ralph-execute)` 是 skill 直调。**严禁** `Bash("maestro \"intent\"")` 裸 intent 调用，CLI 不接受。
 </invariants>
 
 <state_machine>
@@ -56,7 +64,9 @@ HARD RULES:
 <states>
 S_LOCATE        — 定位 session + 找下一个 pending step   PERSIST: —
 S_RESOLVE_ARGS  — 解析占位符 + 丰富参数                  PERSIST: step.args (enriched)
+S_LOAD_CONTEXT  — 加载前序产出 + 发现                    PERSIST: —
 S_EXECUTE       — 执行当前 step                          PERSIST: step.status = "running", session.current_step
+S_POST_ANALYZE  — 产物 vs 目标偏离分析                    PERSIST: step.drift_score, step.drift_correction
 S_POST_EXEC     — 标记完成 + 传播上下文                   PERSIST: step.completion_*, step.status, session.context
 S_HANDLE_FAIL   — 处理失败                               PERSIST: step.status, session.status
 S_COMPLETE      — 所有 step 完成                         PERSIST: session.status = "completed"
@@ -71,15 +81,24 @@ S_LOCATE:
   → S_FALLBACK      WHEN: no running session
 
 S_RESOLVE_ARGS:
-  → S_EXECUTE       DO: A_RESOLVE_ARGS
+  → S_LOAD_CONTEXT  DO: A_RESOLVE_ARGS
+
+S_LOAD_CONTEXT:
+  → S_EXECUTE       DO: A_LOAD_STEP_CONTEXT
 
 S_EXECUTE:
   → END             WHEN: step.decision != null              DO: A_EXEC_DECISION
-  → S_POST_EXEC     WHEN: step.decision == null + ralph complete invoked with DONE|DONE_WITH_CONCERNS  DO: A_EXEC_STEP
-  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit≠0 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
+  → S_POST_ANALYZE  WHEN: step.decision == null + execution succeeded (DONE|DONE_WITH_CONCERNS)  DO: A_EXEC_STEP
+  → S_COMPLETE      WHEN: step.decision == null + ralph next exit code 2 (all steps completed)
+  → S_HANDLE_FAIL   WHEN: step.decision == null + ralph next exit code 1|3 OR ralph complete with NEEDS_RETRY|BLOCKED  DO: A_EXEC_STEP
+
+S_POST_ANALYZE:
+  → S_POST_EXEC     WHEN: drift_score == ALIGNED|MINOR_DRIFT   DO: A_POST_ANALYZE_DRIFT
+  → S_EXECUTE       WHEN: drift_score == MAJOR_DRIFT + not retried  DO: A_POST_ANALYZE_DRIFT (re-execute with correction)
+  → S_POST_EXEC     WHEN: drift_score == MAJOR_DRIFT + retried     DO: A_POST_ANALYZE_DRIFT (proceed with caveats)
 
 S_POST_EXEC:
-  → S_LOCATE        DO: Bash("maestro ralph complete ...") + $maestro-ralph-execute
+  → S_LOCATE        DO: Bash("maestro ralph complete ...") + Skill(maestro-ralph-execute)
                      NOTE: CLI 已写完 completion_*, status, active_step_index；无需额外写盘
 
 S_HANDLE_FAIL:
@@ -93,7 +112,7 @@ S_COMPLETE:
   → END             DO: A_COMPLETE_SESSION
 
 S_FALLBACK:
-  → END             DO: display "无运行中的会话。使用 $maestro 或 $maestro-ralph 创建。"
+  → END             DO: display "无运行中的会话。使用 Skill(maestro) 或 Skill(maestro-ralph) 创建。"
 
 </transitions>
 
@@ -104,7 +123,7 @@ S_FALLBACK:
 1. If session_id provided → load `.workflow/.maestro/{session_id}/status.json`
 2. Else: scan `.workflow/.maestro/*/status.json`, filter `status == "running"`, sort DESC, take first
 3. Extract: session_id, source, steps[], phase, milestone, intent, auto_mode, context, cli_tool, platform, active_step_index
-4. **不在此处选 pending step**——pending 选择由 `maestro ralph next` CLI 内部完成；A_LOCATE_SESSION 只确认 session 存在且 running，由 A_EXEC_STEP 调 CLI 推进
+4. Identify next pending step index: scan `steps[]` in order, find first entry with `status == "pending"` → store as `next_step_index`. This index is passed to A_RESOLVE_ARGS for placeholder enrichment and to A_EXEC_STEP/A_EXEC_DECISION for display. The actual step activation (writing `active_step_index`) is still done by `maestro ralph next` CLI — A_LOCATE_SESSION only reads the index without writing it.
 
 ### A_RESOLVE_ARGS
 
@@ -168,18 +187,39 @@ if goal:
 
 Write enriched args + source_artifact_ref back to status.json.
 
+### A_LOAD_STEP_CONTEXT
+
+加载前序产出和发现，为 inline execution 注入上下文。
+
+1. **Previous step output** — 读前一 completed step 的 `completion_summary` + `completion_caveats` + `completion_decisions` + `completion_deferred`
+2. **Artifacts** — 按 `session.context` 中的路径逐个 Read，提取与当前 step 相关的内容：
+
+   | 当前 stage | 加载什么 | Source |
+   |-----------|---------|--------|
+   | plan | analysis conclusions + scope_verdict | `{context.analysis_dir}/conclusions.json` |
+   | execute | task list + wave assignments | `{context.plan_dir}/TASK-*.json` |
+   | review | changed files + verification results | `{context.scratch_dir}/verification.json` |
+   | test | review findings | `review.json` |
+   | debug | error traces + failing test details | 前一 step 的 `completion_evidence` |
+   | brainstorm | grill report | `{context.grill_id}` report |
+
+3. **Explore if needed** — 产物指向代码位置但缺少上下文 → `maestro explore` 补充（仅 execute/debug/test 且有文件路径引用时）
+4. **Accumulated signals** — 遍历 ALL completed steps → 聚合 caveats + deferred
+
+加载的内容进入会话上下文，后续 inline execution 自动受益。
+
 ### A_EXEC_DECISION
 
 1. Mark step running, write status.json
 2. Display: `[{index}/{total}] ◆ {step.decision} Retry: {retry}/{max}`
-3. `$maestro-ralph` — 直调 ralph 评估 + handoff
+3. `Skill(maestro-ralph)` — 直调 ralph 评估 + handoff
 4. 执行在此结束
 
 ### A_EXEC_STEP
 
-1. **Load** — `Bash("maestro ralph next")`
+1. **Load** — `Bash("maestro ralph next --session {session_id}")`
    - 退出码 0 → 按 stdout 内联执行
-   - 退出码 2 → 交给 S_LOCATE
+   - 退出码 2 → 所有 step 已完成，转 S_COMPLETE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
 2. **Goal context pre-injection**:
@@ -195,11 +235,11 @@ Write enriched args + source_artifact_ref back to status.json.
    </goal_context>
    ```
 3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
-4. **Complete**:
-   - `Bash("maestro ralph complete N --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
-   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
-   - `Bash("maestro ralph retry N")`
-   - `Bash("maestro ralph complete N --status BLOCKED --reason \"...\"")`
+4. **Complete** (all calls MUST include `--session {session_id}`):
+   - `Bash("maestro ralph complete N --session {session_id} --status DONE --summary \"...\" [--evidence <path>] [--decisions \"...\"] [--caveats \"...\"] [--deferred \"...\"]")`
+   - `Bash("maestro ralph complete N --session {session_id} --status DONE_WITH_CONCERNS --summary \"...\" --concerns \"...\"")`
+   - `Bash("maestro ralph retry N --session {session_id}")`
+   - `Bash("maestro ralph complete N --session {session_id} --status BLOCKED --reason \"...\"")`
 
    | Flag | 规则 | 示例 |
    |------|------|------|
@@ -209,11 +249,52 @@ Write enriched args + source_artifact_ref back to status.json.
    | `--deferred` | SHOULD。推迟工作，可多次 | `"性能优化留到 review 后"` |
 5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
-完成后 S_LOCATE 触发 `$maestro-ralph-execute` 直调自调用。
+完成后 S_LOCATE 触发 `Skill(maestro-ralph-execute)` 直调自调用。
+
+### A_POST_ANALYZE_DRIFT
+
+执行完成后、调 ralph complete 前，分析产物与目标的偏离程度并自动修正。
+
+**1. 收集对照基准:**
+
+| 基准来源 | 取值 |
+|---------|------|
+| `step.goal_ref` → goal.done_when | 子目标的完成条件 |
+| `session.boundary_contract.definition_of_done` | 全局验收标准 |
+| `session.execution_criteria` | 执行准则 |
+| `session.intent` | 原始意图 |
+
+**2. 读产物摘要:**
+
+从 A_EXTRACT_STEP_SIGNALS (step 4a) 已提取的 summary + decisions + artifacts 构建产物画像。
+
+**3. 对比评分:**
+
+| 维度 | 检查 |
+|------|------|
+| 覆盖度 | 产物是否覆盖了 goal.done_when 的每个条件 |
+| 方向性 | decisions 是否与 intent 和 boundary 一致 |
+| 完整性 | 预期产物类型是否齐全（如 plan 阶段应有 TASK-*.json） |
+
+**drift_score:**
+- `ALIGNED` — 全部维度通过
+- `MINOR_DRIFT` — 覆盖度/完整性有小缺口，不影响后续
+- `MAJOR_DRIFT` — 方向性偏离或关键产物缺失
+
+**4. 修正动作:**
+
+| drift_score | 动作 |
+|-------------|------|
+| ALIGNED | 正常进入 S_POST_EXEC |
+| MINOR_DRIFT | 将偏离项追加到 completion_caveats，正常 complete |
+| MAJOR_DRIFT + 未重试 | 将偏离分析写入 `step.drift_correction`，回到 S_EXECUTE 重跑（A_LOAD_STEP_CONTEXT 自动加载 drift_correction 作为修正上下文） |
+| MAJOR_DRIFT + 已重试 | 将偏离项写入 caveats + concerns，以 DONE_WITH_CONCERNS complete，由后续 decision node 裁决 |
+
+**5. 写入:** `step.drift_score`, `step.drift_correction`
 
 ### A_RETRY
 
-1. `Bash("maestro ralph retry N")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`
+1. `Bash("maestro ralph retry N --session {session_id}")` — CLI 设 `step.retried = true`, `step.status = "pending"`, `step.completion_confirmed = false`, 清 `active_step_index`
 2. Display: `[{index}/{total}] ↻ {step.skill} retry`
 
 ### A_SKIP_STEP
@@ -224,7 +305,7 @@ Write enriched args + source_artifact_ref back to status.json.
 ### A_PAUSE_SESSION
 
 通常由 `ralph complete N --status BLOCKED --reason "..."` 触发，CLI 已写 `session.status = "paused"`。手动 pause 场景下直接编辑 status.json。
-Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro-ralph continue 恢复。`
+Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。Skill(maestro-ralph, continue) 恢复。`
 
 ### A_COMPLETE_SESSION
 
@@ -258,7 +339,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro
 
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
-| E001 | error | No running session found | Suggest $maestro or $maestro-ralph |
+| E001 | error | No running session found | Suggest Skill(maestro) or Skill(maestro-ralph) |
 | E006 | error | command_path missing/unreachable for 执行 step | `ralph next` 拒绝；编辑 status.json 或重 build |
 | E007 | error | required_reading 引用文件缺失 | `ralph next` 拒绝；CLI stderr 列出缺失路径 |
 | E008 | error | `ralph complete` idx ≠ active_step_index | 编辑 status.json 修正一致性 |
@@ -273,7 +354,7 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro
 - [ ] Session discovery covers maestro-* and ralph-*
 - [ ] `-y` parsed from args 或 session.auto_mode；auto=true 时透传 `-y` 到 skill args
 - [ ] Placeholders resolved；per-skill enrichment 正确
-- [ ] Decision 节点（`step.decision != null`）走 `$maestro-ralph` 直调 handoff（**不调 ralph next CLI**）
+- [ ] Decision 节点（`step.decision != null`）走 `Skill(maestro-ralph)` 直调 handoff（**不调 ralph next CLI**）
 - [ ] 执行 step 通过 `Bash("maestro ralph next")` 加载；CLI 返回拼好的 prompt + completion 协议
 - [ ] required_reading 由 CLI 自动加载并拼入 prompt；缺失 → CLI 退出码 1，pause session
 - [ ] `<deferred_reading>` 由 CLI 记录到 `step.load.deferred_files`，执行阶段按需 Read

package/.codex/skills/maestro-roadmap/SKILL.md

@@ -94,8 +94,14 @@ S_AGGREGATE  -- 精炼、评估、输出                            PERSIST: con
 
 S_PARSE:
   -> S_INPUT        WHEN: create mode (default)
-  -> REVISE_FLOW    WHEN: --revise (load roadmap.md, apply changes, preserve completed phases)
-  -> REVIEW_FLOW    WHEN: --review (read-only health assessment)
+  -> S_REVISE       WHEN: --revise (load roadmap.md, apply changes, preserve completed phases)
+  -> S_REVIEW       WHEN: --review (read-only health assessment)
+
+S_REVISE:
+  -> S_AGGREGATE    DO: A_REVISE — load .workflow/roadmap.md (E005 if missing), apply --revise instructions, preserve completed phases (status!="pending"), rewrite only pending phases, update state.json milestones
+
+S_REVIEW:
+  -> END            DO: A_REVIEW — load .workflow/roadmap.md (E005 if missing), read-only health assessment: phase coverage, dependency integrity, stale phases, progress %. Display report. No writes.
 
 S_INPUT:
   -> S_CSV_GEN      DO: parse requirement (text/@file), load context-package.json if --from, codebase detection, load specs

package/.codex/skills/maestro-tools-execute/SKILL.md

@@ -31,11 +31,11 @@ Empty arguments enters interactive mode: list all tools for user selection.
 
 ### Step 1: Load Tool
 
-**By name**:
+**By name** (search all categories first, then filter):
 ```bash
-maestro load --type spec --category coding --keyword <name>
+maestro search "<name>" --type spec
 ```
-Match tool entries whose title or keywords contain the name.
+Match tool entries whose title or keywords contain the name across all categories. If no results, retry with `maestro search "<name>" --type knowhow`. Present matches to user if multiple found.
 
 **By category**:
 ```bash
@@ -44,7 +44,11 @@ maestro load --type spec --category <category>
 Extract tool entries from output, list available tools.
 
 **Empty args**:
-Load all tool entries, present to user with request_user_input for selection.
+Search all tool entries across all categories:
+```bash
+maestro search "tool" --type knowhow
+```
+Present to user with request_user_input for selection.
 
 ### Step 2: Display Tool
 

package/.codex/skills/maestro-tools-register/SKILL.md

@@ -6,7 +6,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
-Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter. Once registered, entries are auto-discovered by downstream agents via `spec load --category` — plan agents pick up design/architecture flows, test agents pick up verification methods, coding agents pick up execution steps.
+Codify reusable business processes as knowhow documents with `tool: true` in YAML frontmatter.
+
+**Storage architecture**: `knowhow/` is the single source of truth for tool content. Spec index entries (`specs/`) serve only as discovery pointers — they reference knowhow documents via `ref:` links but never store tool steps directly. Downstream agents discover tools via `maestro search` or `maestro load --type knowhow --keyword <name>`, with spec index providing category-based routing.
 
 Four modes:
 
@@ -30,7 +32,7 @@ $maestro-tools-register "promote RCP-db-migration-rollback as test tool"
 $maestro-tools-register "promote knowhow-auth-api to coding tool"
 ```
 
-**Tool registration**: Creates knowhow documents in `knowhow/` folder with `tool: true` in YAML frontmatter. Tools are auto-discovered by `spec load` based on category + tool flag.
+**Tool registration**: Creates knowhow documents in `.workflow/knowhow/` (single source of truth for tool content). Tools are discovered via `maestro search` or `maestro load --type knowhow` by category + tool flag.
 
 **Knowhow format**:
 ```yaml
@@ -149,8 +151,9 @@ tool: true
 
 ### Step 6: Verify
 
-- `maestro load --type spec --category <category> --keyword <keyword>` to confirm loadable
-- Display result: title, category, keywords, storage location
+- Verify knowhow document exists: `maestro load --type knowhow --id <id>` to confirm loadable
+- Verify discovery works: `maestro search "<keyword>" --type knowhow` to confirm searchable
+- Display result: title, category, keywords, storage location (knowhow/)
 
 </execution>
 
@@ -163,9 +166,10 @@ tool: true
 </error_codes>
 
 <success_criteria>
-- [ ] Tool registered as knowhow document with `tool: true` frontmatter
+- [ ] Tool registered as knowhow document in `.workflow/knowhow/` with `tool: true` frontmatter
 - [ ] category attribute correctly set
 - [ ] keywords auto-extracted (3-5 terms)
-- [ ] Loadable via `spec load --category <category>`
+- [ ] Discoverable via `maestro search` and `maestro load --type knowhow`
 - [ ] Long processes use ref mode with knowhow file created
+- [ ] No tool content duplicated in spec index — spec entries use `ref:` links only
 </success_criteria>

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -2,7 +2,7 @@
 name: maestro-ui-codify
 description: Extract design system from code, generate reference package, persist as knowledge assets
 argument-hint: "<source-path> [--package-name <name>] [--output-dir <path>] [--overwrite] [-y]"
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -68,13 +68,13 @@ $maestro-ui-codify "src/styles" --output-dir .workflow/packages --overwrite -y
 ### tasks.csv (Master State)
 
 ```csv
-id,wave,title,description,agent_type,deps
-"discover-1","1","Discover design files","Scan source directory, categorize files by type (CSS/SCSS/JS/TS/HTML), build file inventory with import relationships","discover",""
-"style-1","2","Extract visual design tokens","Extract color, typography, spacing, border, shadow tokens from source files. Output design-tokens.json","extract-style","discover-1"
-"anim-1","2","Extract animation tokens","Extract animation/transition declarations: keyframes, durations, easings, motion patterns. Output animation-tokens.json","extract-animation","discover-1"
-"layout-1","2","Extract layout patterns","Extract component layout patterns: grid/flex systems, responsive breakpoints, container patterns. Output layout-templates.json","extract-layout","discover-1"
-"package-1","3","Generate reference package","Copy token JSONs to package dir, generate preview.html + preview.css interactive showcase","package","style-1;anim-1;layout-1"
-"knowhow-1","4","Build knowledge assets","Read token JSONs, build knowhow-manifest.json, write knowhow files + spec entries, cleanup temp workspace","knowhow","package-1"
+id,wave,title,description,agent_type,deps,status
+"discover-1","1","Discover design files","Scan source directory, categorize files by type (CSS/SCSS/JS/TS/HTML), build file inventory with import relationships","discover","","pending"
+"style-1","2","Extract visual design tokens","Extract color, typography, spacing, border, shadow tokens from source files. Output design-tokens.json","extract-style","discover-1","pending"
+"anim-1","2","Extract animation tokens","Extract animation/transition declarations: keyframes, durations, easings, motion patterns. Output animation-tokens.json","extract-animation","discover-1","pending"
+"layout-1","2","Extract layout patterns","Extract component layout patterns: grid/flex systems, responsive breakpoints, container patterns. Output layout-templates.json","extract-layout","discover-1","pending"
+"package-1","3","Generate reference package","Copy token JSONs to package dir, generate preview.html + preview.css interactive showcase","package","style-1;anim-1;layout-1","pending"
+"knowhow-1","4","Build knowledge assets","Read token JSONs, build knowhow-manifest.json, write knowhow files + spec entries, cleanup temp workspace","knowhow","package-1","pending"
 ```
 
 **Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns. Output columns are returned exclusively via output_schema.
@@ -89,6 +89,7 @@ id,wave,title,description,agent_type,deps
 | `description` | Input | Detailed instructions for this task |
 | `agent_type` | Input | Agent type: discover/extract-style/extract-animation/extract-layout/package/knowhow |
 | `deps` | Input | Semicolon-separated dependency task IDs |
+| `status` | Lifecycle | Task lifecycle status, initialized to `pending`. Updated to `completed`/`failed` after wave merge via `result_status` mapping |
 | `result_status` | Output | `completed` / `failed` (returned via output_schema) |
 | `findings` | Output | Key findings summary (max 500 chars, via output_schema) |
 | `output_path` | Output | Path to generated artifact (via output_schema) |
@@ -187,6 +188,10 @@ sessionFolder=".workflow/.csv-wave/${session_date}-ui-codify-${session_slug}"
 mkdir -p "$sessionFolder"
 ```
 
+### Step 2c.1: Confirmation Gate
+
+Unless `-y/--yes`, display source path, package name, output directory, overwrite policy, and wave plan summary. Use `request_user_input` to confirm before proceeding. Under `-y`, skip confirmation.
+
 ### Step 3: Generate tasks.csv
 
 Build the master CSV with 4 waves. The `description` column contains full agent instructions.
@@ -329,7 +334,7 @@ spawn_agents_on_csv({
 
 Merge wave-2-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `wave-2.csv` and `wave-2-results.csv`.
 
-**Degradation**: If animation agent fails (W001), continue — animation is optional. If style or layout agent fails, warn but continue with available results.
+**Degradation**: If animation agent fails (W001), continue — animation is optional. If style agent fails, Wave 3 proceeds without design-tokens.json but artifact verification will report `incomplete` status. If layout agent fails, Wave 3 proceeds without layout-templates.json but artifact verification will report `incomplete` status. If both style AND layout fail, skip Wave 3 and Wave 4, mark session `degraded`, and report partial results only.
 
 #### Wave 3: Reference Package (Barrier)
 

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 ---
 
 <purpose>
-Single-wave parallel execution -- 5 independent doc generator agents each analyze a different documentation dimension of the codebase. All agents run concurrently with no dependencies. This is a destructive operation that rebuilds the entire `.workflow/codebase/` directory from scratch.
+Two-wave parallel execution -- Wave 1: 3 scanner agents (Component Scanner, Feature Mapper, Requirement Linker) analyze the codebase in parallel. Wave 2: 2 writer agents (Tech Registry Writer, Feature Map Writer) consume scanner results and write documentation files. This is a destructive operation that rebuilds the entire `.workflow/codebase/` directory from scratch.
 
 **Core workflow**: Prepare Directory -> Decompose Doc Dimensions -> Parallel Generation -> Assemble doc-index.json
 
@@ -25,11 +25,12 @@ Single-wave parallel execution -- 5 independent doc generator agents each analyz
 |     +-- Generate tasks.csv with 5 doc generator tasks                    |
 |     +-- All tasks wave 1 (no dependencies)                               |
 |                                                                           |
-|  Phase 2: Wave Execution (Single Wave)                                    |
-|     +-- Wave 1: All 5 generators run concurrently                        |
+|  Phase 2: Wave Execution (Two Waves)                                      |
+|     +-- Wave 1: 3 scanners run concurrently                              |
 |     |   +-- Component Scanner (TC-* entries)                             |
 |     |   +-- Feature Mapper (FT-* entries)                                |
 |     |   +-- Requirement Linker (REQ-* entries, if specs exist)           |
+|     +-- Wave 2: 2 writers consume scanner results                        |
 |     |   +-- Tech Registry Writer (tech-registry/*.md)                    |
 |     |   +-- Feature Map Writer (feature-maps/*.md)                       |
 |     +-- discoveries.ndjson shared (append-only)                          |
@@ -80,12 +81,12 @@ When `--yes` or `-y`: Auto-confirm rebuild (implies --force), skip all prompts.
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,doc_dimension,output_path,deps,context_from,wave
-"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Return JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols via output_schema. Do NOT write files — orchestrator assembles doc-index.json in Phase 3.","components","<ABS_WORKFLOW>/codebase/doc-index.json#components","","","1"
-"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if <ABS_WORKFLOW>/blueprint/ exists. Return JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase via output_schema. Do NOT write files.","features","<ABS_WORKFLOW>/codebase/doc-index.json#features","","","1"
-"3","Requirement Linker","If <ABS_WORKFLOW>/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Return JSON arrays for requirements and architecture_decisions via output_schema. Do NOT write files.","requirements","<ABS_WORKFLOW>/codebase/doc-index.json#requirements","","","1"
-"4","Tech Registry Writer","For each component discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Also write <ABS_WORKFLOW>/codebase/tech-registry/_index.md with the component table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","tech-registry","<ABS_WORKFLOW>/codebase/tech-registry/","","","1"
-"5","Feature Map Writer","For each feature discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Also write <ABS_WORKFLOW>/codebase/feature-maps/_index.md with the feature table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","feature-maps","<ABS_WORKFLOW>/codebase/feature-maps/","","","1"
+id,title,description,doc_dimension,output_path,deps,context_from,wave,status
+"1","Component Scanner","Scan all source directories for components: models, services, controllers, utils, types, config, middleware, core modules. For each component extract exported symbols, determine type, record code locations. Return JSON array of component entries with id (TC-NNN), name, type, code_locations, symbols via output_schema. Do NOT write files — orchestrator assembles doc-index.json in Phase 3.","components","<ABS_WORKFLOW>/codebase/doc-index.json#components","","","1","pending"
+"2","Feature Mapper","Group discovered components by domain/functional area using directory proximity, naming patterns, and import relationships. Map features to requirements if <ABS_WORKFLOW>/blueprint/ exists. Return JSON array of feature entries with id (FT-NNN), name, status, component_ids, requirement_ids, phase via output_schema. Do NOT write files.","features","<ABS_WORKFLOW>/codebase/doc-index.json#features","","","1","pending"
+"3","Requirement Linker","If <ABS_WORKFLOW>/blueprint/ exists, scan BLP-*/requirements/REQ-*.md files. Parse requirement metadata (title, priority, acceptance_criteria). Match requirements to features by keyword analysis. Also scan for ADR-*.md architecture decisions. Return JSON arrays for requirements and architecture_decisions via output_schema. Do NOT write files.","requirements","<ABS_WORKFLOW>/codebase/doc-index.json#requirements","","","1","pending"
+"4","Tech Registry Writer","For each component discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/tech-registry/{slug}.md with: ID, type, features, code locations, exported symbols, dependencies. Also write <ABS_WORKFLOW>/codebase/tech-registry/_index.md with the component table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","tech-registry","<ABS_WORKFLOW>/codebase/tech-registry/","1;2;3","1;2;3","2","pending"
+"5","Feature Map Writer","For each feature discovered, use the Write tool to create a markdown documentation file at <ABS_WORKFLOW>/codebase/feature-maps/{slug}.md with: ID, status, phase, requirements, component table. Also write <ABS_WORKFLOW>/codebase/feature-maps/_index.md with the feature table. After all writes, verify every intended file exists with Glob and return file count + absolute paths via output_schema. MUST use the Write tool — files on disk are the deliverable, do NOT return file content as text.","feature-maps","<ABS_WORKFLOW>/codebase/feature-maps/","1;2;3","1;2;3","2","pending"
 ```
 
 **Path resolution (orchestrator MUST do BEFORE writing tasks.csv)**: substitute `<ABS_WORKFLOW>` with the absolute path to the project's `.workflow/` directory (e.g. `D:/maestro2/.workflow`). Agent Write tool requires absolute paths — passing relative `.workflow/...` literals will fail.
@@ -101,7 +102,8 @@ id,title,description,doc_dimension,output_path,deps,context_from,wave
 | `output_path` | Input | Target output path in .workflow/codebase/ |
 | `deps` | Input | Empty (all independent) |
 | `context_from` | Input | Empty (no cross-task context needed) |
-| `wave` | Computed | Always 1 (single wave, independent parallel) |
+| `wave` | Computed | 1 (scanners, independent parallel) or 2 (writers, depend on wave 1) |
+| `status` | Lifecycle | Initialized to `pending`, updated to `completed`/`failed` after wave merge |
 
 **Output columns** (returned exclusively via `output_schema`, NOT in wave CSV):
 
@@ -124,7 +126,7 @@ Single wave generates `wave-1.csv`. No `prev_context` needed (all tasks independ
 3. **Discovery Board is Append-Only**: Generators share findings via NDJSON
 4. **Partial Results OK**: If 3/5 generators succeed, still assemble available docs
 5. **Destructive by Design**: This is a full rebuild -- existing codebase/ is cleared
-6. **Single Wave**: All generators are independent, no wave ordering needed
+6. **Two Waves**: Wave 1 (Scanner/Mapper/Linker, independent parallel), Wave 2 (Writers, depend on wave 1 results via context_from)
 7. **Cleanup Temp Files**: Remove wave-1.csv after results are merged
 8. **DO NOT STOP**: Execute until all generators complete or fail
 9. **Absolute Paths Only**: All paths in `description` and `output_path` MUST be absolute before tasks.csv is written. Orchestrator substitutes `<ABS_WORKFLOW>` placeholder; never let it leak into a spawned agent's prompt.
@@ -182,6 +184,8 @@ Parse `$ARGUMENTS` to extract:
 Session ID: `{YYYYMMDD}-rebuild-full`
 Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 
+**Continue mode** (`--continue`): Locate existing session by ID or most recent. Read `tasks.csv`, identify pending/failed rows. Resume from next pending wave — do NOT re-run Phase 1 cleanup. If no session found, list available sessions and exit.
+
 ### Phase 1: Setup -> CSV
 
 **Objective**: Validate prerequisites, prepare directory, detect source dirs, generate tasks.csv.
@@ -201,11 +205,11 @@ Session folder: `.workflow/.csv-wave/{sessionId}/` — create via `mkdir -p`
 6. **Generate tasks.csv**: 5 rows, all wave 1, no dependencies
 7. **User validation**: Display doc generator breakdown (skip if AUTO_YES)
 
-### Phase 2: Wave Execution (Single Wave)
+### Phase 2: Wave Execution (Two Waves)
 
-**Objective**: Run all 5 doc generators concurrently via spawn_agents_on_csv.
+**Objective**: Run scanners (wave 1) then writers (wave 2) via spawn_agents_on_csv.
 
-#### Wave 1: All Generators (Parallel)
+#### Wave 1: Scanners (Parallel)
 
 Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-1.csv` (no prev_context needed, all independent).
 
@@ -232,6 +236,24 @@ spawn_agents_on_csv({
 
 Merge `wave-1-results.csv` into master `tasks.csv`: map `result_status` -> master `status`, `result_findings` -> master `findings`, copy `error` as-is. After merge, delete temporary files (`wave-1.csv` and `wave-1-results.csv`).
 
+#### Wave 2: Writers (Parallel, depends on Wave 1)
+
+Filter master `tasks.csv` for `wave == 2 AND status == pending`. Build `prev_context` from wave 1 findings (scanner/mapper/linker results). Write `wave-2.csv` with `prev_context` column.
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-2.csv`,
+  id_column: "id",
+  instruction: REBUILD_INSTRUCTION,
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
+  output_schema: { /* same as wave 1 */ }
+})
+```
+
+Merge `wave-2-results.csv` into master `tasks.csv`. Delete temporary files.
+
 #### Rebuild Worker Contract (REBUILD_INSTRUCTION)
 
 ```

package/.codex/skills/manage-codebase-refresh/SKILL.md

@@ -32,7 +32,7 @@ Verify `.workflow/` exists (E001) and `.workflow/codebase/` exists (E002 -- use
 
 ### Step 2: Detect Changes
 
-Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Run `git diff --name-only --since="{baseline}" HEAD`. If no changes: W001, exit.
+Resolve baseline: `--since` flag > `state.json.codebase_last_refreshed` > `codebase_last_rebuilt` > 7-day fallback. Find the baseline commit via `git log --since="{baseline}" --reverse --format="%H" | head -1`. If no commit found, use `HEAD~1`. Then run `git diff --name-only {baseline_commit}..HEAD`. If no changes: W001, exit.
 
 ### Step 3: Map Changes to Docs
 

package/.codex/skills/manage-drift-realign/SKILL.md

@@ -97,11 +97,11 @@ $manage-drift-realign --continue "20260624-drift-realign"
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,scan_scope,output_format,deps,context_from,wave
-"1","Roadmap Scanner","Scan .workflow/roadmap.md and .workflow/state.json for drift against code reality. Read timeline.json for git change context. Detect: phantom_phase (P0), stale_progress (P1), milestone_mismatch (P0), outdated_criteria (P1), dependency_ghost (P1), timeline_impossible (P2). For each finding: verify against code/state.json before reporting. Return JSON array of DriftFinding objects via output_schema.","roadmap","json","","","1"
-"2","Spec Scanner","Scan .workflow/specs/*.md spec-entry blocks for drift against actual code patterns. Read timeline.json hot_paths to focus on high-change areas. Detect: convention_violation (P0), dead_import_pattern (P1), architecture_breach (P0), stale_dependency (P1), naming_drift (P2), test_convention_gap (P2). {DEPTH_INSTRUCTION}. Return JSON array of DriftFinding objects via output_schema.","spec","json","","","1"
-"3","Codebase Scanner","Scan .workflow/codebase/*.md and doc-index.json for drift against current code structure. Read timeline.json for git changes. Detect: architecture_outdated (P0), feature_missing (P1), tech_stack_changed (P0), concern_drift (P1), doc_index_stale (P0). {DEPTH_INSTRUCTION}. Return JSON array of DriftFinding objects via output_schema.","codebase","json","","","1"
-"4","Artifact Scanner","Scan .workflow/issues/issues.jsonl, .workflow/knowhow/*.md, .workflow/project.md, and state.json accumulated_context for drift. Read timeline.json for git context. Detect: issue_code_ref_dead (P1), issue_stale_open (P1), knowhow_code_ref_dead (P1), orphan_session (P2), project_tech_drift (P0), project_req_drift (P1), accumulated_stale (P1), deferred_resolved (P2). Return JSON array of DriftFinding objects via output_schema.","artifact","json","","","1"
+id,title,description,scan_scope,output_format,deps,context_from,wave,status
+"1","Roadmap Scanner","Scan .workflow/roadmap.md and .workflow/state.json for drift against code reality. Read timeline.json for git change context. Detect: phantom_phase (P0), stale_progress (P1), milestone_mismatch (P0), outdated_criteria (P1), dependency_ghost (P1), timeline_impossible (P2). For each finding: verify against code/state.json before reporting. Return JSON array of DriftFinding objects via output_schema.","roadmap","json","","","1","pending"
+"2","Spec Scanner","Scan .workflow/specs/*.md spec-entry blocks for drift against actual code patterns. Read timeline.json hot_paths to focus on high-change areas. Detect: convention_violation (P0), dead_import_pattern (P1), architecture_breach (P0), stale_dependency (P1), naming_drift (P2), test_convention_gap (P2). {DEPTH_INSTRUCTION}. Return JSON array of DriftFinding objects via output_schema.","spec","json","","","1","pending"
+"3","Codebase Scanner","Scan .workflow/codebase/*.md and doc-index.json for drift against current code structure. Read timeline.json for git changes. Detect: architecture_outdated (P0), feature_missing (P1), tech_stack_changed (P0), concern_drift (P1), doc_index_stale (P0). {DEPTH_INSTRUCTION}. Return JSON array of DriftFinding objects via output_schema.","codebase","json","","","1","pending"
+"4","Artifact Scanner","Scan .workflow/issues/issues.jsonl, .workflow/knowhow/*.md, .workflow/project.md, and state.json accumulated_context for drift. Read timeline.json for git context. Detect: issue_code_ref_dead (P1), issue_stale_open (P1), knowhow_code_ref_dead (P1), orphan_session (P2), project_tech_drift (P0), project_req_drift (P1), accumulated_stale (P1), deferred_resolved (P2). Return JSON array of DriftFinding objects via output_schema.","artifact","json","","","1","pending"
 ```
 
 **Substitutions (orchestrator MUST do BEFORE writing tasks.csv)**:
@@ -119,6 +119,7 @@ id,title,description,scan_scope,output_format,deps,context_from,wave
 | `deps` | Empty (all independent) |
 | `context_from` | Empty (all read timeline.json directly) |
 | `wave` | Always 1 (single wave) |
+| `status` | `pending` / `running` / `completed` / `failed` |
 
 **Output columns** (returned exclusively via `output_schema`):
 
@@ -309,8 +310,8 @@ maestro spec conflict list
 For spec entries with existing conflict-markers that also appear in scanner findings: merge and elevate to P0.
 
 **Step 3.3: Triage**
-- If `--report` → skip to Phase 4 report
-- If `--dry-run` → display all findings with suggested actions, skip Phase 4 apply
+- If `--report` → generate report output only (Phase 4 Step 4.3), skip triage and all file mutations (no backups, no action application, no state.json update)
+- If `--dry-run` → display all findings with suggested actions, skip all file mutations in Phase 4 (no backups, no action application, no state.json update, no drift-log.jsonl writes)
 - If `--auto-archive` → auto-apply each finding's `suggested_action` for P1/P2; only P0 gets interactive review
 - Otherwise → interactive triage per finding using `request_user_input`:
 
@@ -340,13 +341,15 @@ Export master `tasks.csv` as `results.csv`.
 
 ### Phase 4: Apply + Report
 
-**Step 4.1: Backup**
+> **Write boundary**: If `--report`, skip directly to Step 4.3 (report generation only). If `--dry-run`, skip Steps 4.1 and 4.2 entirely — no backup, no file mutations, no state.json update. Only Step 4.3 (report) and Step 4.4 (context.md) execute.
+
+**Step 4.1: Backup** (skipped by --report and --dry-run)
 ```bash
 mkdir -p .workflow/.trash/drift-realign-{timestamp}/
 ```
 Copy all affected files + state.json to backup. If backup fails → abort (E005).
 
-**Step 4.2: Apply actions**
+**Step 4.2: Apply actions** (skipped by --report and --dry-run)
 
 | Action | Implementation |
 |--------|---------------|
@@ -354,16 +357,16 @@ Copy all affected files + state.json to backup. If backup fails → abort (E005)
 | skip | Write drift-log.jsonl entry (action=skipped) |
 | update | Prepend `<!-- DRIFT-TODO: {hint} (DFT-{id}, {date}) -->` to target file |
 | archive | Move file to `.trash/{timestamp}/`, update state.json refs |
-| rebuild | Collect targets; after all other actions: invoke $quality-sync --full |
+| rebuild | Collect targets; after all other actions: suggest `$quality-sync --full` with target list. Require explicit user confirmation before invoking (use `request_user_input`). If declined, log as `action=rebuild_deferred` in drift-log.jsonl |
 
-After rebuild: if sync reports major structural changes → suggest $manage-codebase-rebuild.
+After rebuild (if confirmed and executed): if sync reports major structural changes → suggest $manage-codebase-rebuild.
 
 Conflict-marker cleanup: for update/archive targets with existing conflict-markers:
 ```bash
 maestro spec conflict clear <file> <line>
 ```
 
-Update state.json: `last_drift_realign = now` (atomic: backup → write → verify).
+Update state.json: `last_drift_realign = now` (atomic: backup → write → verify). Skipped when `--report` or `--dry-run` is active.
 
 **Step 4.3: Generate report**
 

package/.codex/skills/manage-harvest/SKILL.md

@@ -64,7 +64,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 (standard mode) or Stage 9
 - Component-level pitfalls → `learning` category
 - Quality enforcement rules → `quality` category
 - Wiki: `maestro wiki create --type <type> --slug harvest-<source_type>-<short_id>`
-- Spec: `maestro wiki append spec-<file> --body "<content>" --keywords "<kws>"` (unified write path) or `$spec-add "<category> <content>"`
+- Spec: `$spec-add "<category> <content>"` (single source of truth — always use spec-add for spec routing; do NOT use `maestro wiki append` for spec entries)
 - Issue: append to `issues.jsonl` matching canonical schema, with `source: "harvest"` field (distinguishes from `manage-issue-discover`, which uses `source: "discover"` — required for cross-skill dedup when both write concurrently)
 
 **Next steps:** `$manage-wiki health`, `maestro search --type note`, `$wiki-connect --fix`, `$wiki-digest`, `$manage-issue list --source harvest`, `$manage-knowledge-audit --scope spec` (when specs extracted, check for conflicts)