maestro-flow 0.5.36 → 0.5.38

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

@@ -1,119 +1,119 @@
----
-name: maestro-overlay
-description: Create or edit command overlays from natural language
-argument-hint: "<intent> | --list | --remove <name>"
-allowed-tools: Read, Write, Bash, Glob, Grep
----
-
-<purpose>
-4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
-
-```
-Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
-(or --list /      (read command        (apply_patch    (exec_command +
-  --remove)         XML sections)       to overlays/)    banner)
-```
-
-**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
-
-**Patch modes**: `append`, `prepend`, `replace`, `new-section`
-</purpose>
-
-<context>
-
-```bash
-$maestro-overlay "always run CLI verification after maestro-execute"
-$maestro-overlay "require reading doc X before maestro-plan"
-$maestro-overlay "--list"
-$maestro-overlay "--remove cli-verify-after-execute"
-```
-
-**Flags**:
-- `<intent>` — Natural-language description of what to inject and where
-- `--list` — Show installed overlays and their applied state
-- `--remove <name>` — Strip overlay from targets and delete its file
-
-**Overlay storage**:
-- User overlays: `~/.maestro/overlays/*.json`
-- Shared docs: `~/.maestro/overlays/docs/*.md`
-- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
-
-</context>
-
-<invariants>
-1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
-2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
-3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
-4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
-5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
-6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
-</invariants>
-
-<execution>
-
-### Step 1: Parse User Intent
-
-**Quick-exit paths**:
-- `--list` → run `maestro overlay list`, then stop
-- `--remove <name>` → run `maestro overlay remove <name>`, then stop
-
-**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
-
-### Step 2: Identify Targets and Injection Points
-
-Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). Select injection point:
-
-| Intent type | Section | Mode |
-|-------------|---------|------|
-| New step after execution | `execution` | `append` |
-| Required reading / prerequisite | `required_reading` | `append` |
-| Preconditions / gating | `context` | `append` |
-| Output quality gate | `success_criteria` | `append` |
-| Brand-new section | `execution` | `new-section` (with `afterSection`) |
-
-### Step 3: Draft Overlay JSON
-
-Build slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
-
-```json
-{
-  "name": "<slug>",
-  "description": "<short summary>",
-  "targets": ["<command-name>"],
-  "priority": 50,
-  "enabled": true,
-  "patches": [{
-    "section": "<section>",
-    "mode": "<append|prepend|replace|new-section>",
-    "content": "<injected markdown with (overlay) heading>"
-  }]
-}
-```
-
-**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
-
-### Step 4: Install via CLI and Report
-
-Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
-
-Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
-
-</execution>
-
-<error_codes>
-
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
-| E002 | error | No targets found (all commands missing) | Check command name spelling |
-| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
-| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
-
-</error_codes>
-
-<success_criteria>
-- [ ] Intent parsed and targets identified
-- [ ] Overlay JSON drafted with correct section and mode
-- [ ] `maestro overlay add` executed successfully
-- [ ] Report displayed with apply/remove/inspect commands
-</success_criteria>
+---
+name: maestro-overlay
+description: Create or edit command overlays from natural language
+argument-hint: "<intent> | --list | --remove <name>"
+allowed-tools: Read, Write, Bash, Glob, Grep
+---
+
+<purpose>
+4-step pipeline: parse intent → identify targets + injection points → draft overlay JSON → install via CLI and report. Overlays are JSON patch files that augment `.claude/commands/*.md` non-invasively. They survive reinstalls because `maestro install` auto-reapplies them. Each overlay is idempotent: the patcher wraps content in hashed HTML-comment markers, so re-running `maestro overlay apply` produces no file changes.
+
+```
+Parse Intent  →  Identify Targets  →  Draft JSON  →  Install + Report
+(or --list /      (read command        (apply_patch    (exec_command +
+  --remove)         XML sections)       to overlays/)    banner)
+```
+
+**Available injection sections**: `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`
+
+**Patch modes**: `append`, `prepend`, `replace`, `new-section`
+</purpose>
+
+<context>
+
+```bash
+$maestro-overlay "always run CLI verification after maestro-execute"
+$maestro-overlay "require reading doc X before maestro-plan"
+$maestro-overlay "--list"
+$maestro-overlay "--remove cli-verify-after-execute"
+```
+
+**Flags**:
+- `<intent>` — Natural-language description of what to inject and where
+- `--list` — Show installed overlays and their applied state
+- `--remove <name>` — Strip overlay from targets and delete its file
+
+**Overlay storage**:
+- User overlays: `~/.maestro/overlays/*.json`
+- Shared docs: `~/.maestro/overlays/docs/*.md`
+- Shipped examples: `~/.maestro/overlays/_shipped/` (read-only)
+
+</context>
+
+<invariants>
+1. **Quick-exit first**: `--list` and `--remove` skip all intent parsing
+2. **Pristine source preferred**: Always read `.claude/commands/<name>.md` for the untouched command spec before deciding injection point
+3. **Idempotent content**: Injected blocks use hashed comment markers — re-runs produce no changes
+4. **Heading required**: Every injected block must start with a `## <Title> (overlay)` heading
+5. **Validate before report**: Run `maestro overlay add` successfully before displaying the report banner
+6. **Max 2 clarification questions**: If intent is ambiguous, ask at most 2 focused questions then proceed with best guess
+</invariants>
+
+<execution>
+
+### Step 1: Parse User Intent
+
+**Quick-exit paths**:
+- `--list` → run `maestro overlay list`, then stop
+- `--remove <name>` → run `maestro overlay remove <name>`, then stop
+
+**Ambiguous intent**: If target command or injection point unclear, ask up to 2 focused questions.
+
+### Step 2: Identify Targets and Injection Points
+
+Read pristine command source from `$PKG_ROOT/.claude/commands/<name>.md` (fallback: `~/.claude/commands/<name>.md`). Select injection point:
+
+| Intent type | Section | Mode |
+|-------------|---------|------|
+| New step after execution | `execution` | `append` |
+| Required reading / prerequisite | `required_reading` | `append` |
+| Preconditions / gating | `context` | `append` |
+| Output quality gate | `success_criteria` | `append` |
+| Brand-new section | `execution` | `new-section` (with `afterSection`) |
+
+### Step 3: Draft Overlay JSON
+
+Build slug from intent (kebab-case, lowercase, max 40 chars). Write overlay to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary>",
+  "targets": ["<command-name>"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [{
+    "section": "<section>",
+    "mode": "<append|prepend|replace|new-section>",
+    "content": "<injected markdown with (overlay) heading>"
+  }]
+}
+```
+
+**Content guidelines**: Lead with `## Title (overlay)` heading. Use `@~/.maestro/...` references. Keep concise.
+
+### Step 4: Install via CLI and Report
+
+Run `maestro overlay add ~/.maestro/overlays/<slug>.json`. On validation failure, fix JSON and retry (max 2).
+
+Display report with name, path, targets (applied/skipped), and commands for re-apply/remove/inspect.
+
+</execution>
+
+<error_codes>
+
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | `maestro overlay add` validation failed | Fix JSON syntax or section name, retry |
+| E002 | error | No targets found (all commands missing) | Check command name spelling |
+| E003 | error | `--remove` target not found in overlay store | Run `--list` to see installed overlays |
+| W001 | warning | One or more targets skipped (command missing from install) | Overlay still installed; applies when command is added |
+
+</error_codes>
+
+<success_criteria>
+- [ ] Intent parsed and targets identified
+- [ ] Overlay JSON drafted with correct section and mode
+- [ ] `maestro overlay add` executed successfully
+- [ ] Report displayed with apply/remove/inspect commands
+</success_criteria>

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

@@ -88,7 +88,7 @@ Write resolved milestone into PLN artifact registration and `plan.json.milestone
 **Session**: `.workflow/.csv-wave/{YYYYMMDD}-plan-P{N}-{slug}/`
 **Scratch**: `.workflow/scratch/{YYYYMMDD}-plan-P{N}-{slug}/` (.task/ subdir)
 
-**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro spec load --category arch`, team preflight `maestro collab preflight`.
+**Pre-load** (optional): context-package.json (via `--from`, takes precedence), context.md (prior analyze), conclusions.json, codebase ARCHITECTURE.md, `maestro search`, `maestro load --type spec --category arch`, team preflight `maestro collab preflight`.
 
 **D-008 Ad-hoc Milestone Auto-Creation**: When scope resolves to `standalone` via standard resolution (routes 6 or 7, NOT via `--from`), and `state.json.current_milestone == null`, auto-create an adhoc milestone:
 ```

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

@@ -51,7 +51,7 @@ Extract from arguments:
 
 Read `.workflow/state.json` and `.workflow/project.md` if they exist. If `.workflow/` does not exist, create minimal scratch structure anyway (quick works without full init).
 
-Load coding specs + tools if available: `maestro spec load --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro spec load --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro wiki load <id>`. All optional — proceed without if unavailable.
+Load coding specs + tools if available: `maestro load --type spec --category coding`. If the task involves frontend/UI work (description contains component, page, style, layout, CSS, HTML, frontend), also run `maestro load --type spec --category ui`. Browse wiki: `maestro search --category coding`, load relevant entries via `maestro load --type knowhow --id <id>`. All optional — proceed without if unavailable.
 
 ### Step 3: Create Scratch Directory
 
@@ -70,7 +70,7 @@ Analyze the task for gray areas and ambiguities:
 ### Step 5: Quick Analysis
 
 Rapid codebase exploration focused on the task:
-1. Search for related files using Grep/Glob
+1. Search for related files using `maestro explore` (preferred, fallback Grep/Glob)
 2. Identify existing patterns to follow
 3. Map dependencies and integration points
 4. Write analysis findings to `context.md` (append if --discuss created it)

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-ralph
 description: Use when the optimal command sequence is unclear and needs automated state-based determination
-argument-hint: "<intent> [-y] | status [session-id] | continue [session-id]"
+argument-hint: "<intent> [-y] | status [session-id] | continue [session-id] | --amend [change]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
@@ -48,15 +48,20 @@ Mutual invocation with `$maestro-ralph-execute` forms a self-perpetuating work l
 ```
 </purpose>
 
+<deferred_reading>
+- [ralph-amend-goal.md](~/.maestro/workflows/ralph-amend-goal.md) — read when `--amend` flag active for goal amendment flow
+</deferred_reading>
+
 <context>
 $ARGUMENTS — intent text, flags, or keywords.
 
 **Parse:**
 ```
 -y flag                          → auto_confirm = true
+--amend / -a                     → amend_mode = true (running session 存在时触发目标修改流程)
 .md/.txt path                    → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
 status|continue + session-id     → 当 intent ∈ {status,continue} 且后续 token 匹配 ralph-*|maestro-* → target_session_id
-Remaining                        → intent
+Remaining                        → intent (amend_mode 时为 change_request)
 ```
 
 **State files:**
@@ -100,6 +105,7 @@ S_CONFIRM         — 用户确认                             PERSIST: —
 S_DISPATCH        — 移交 maestro-ralph-execute           PERSIST: —
 S_DECISION_EVAL   — 委托评估质量门                       PERSIST: —
 S_APPLY_VERDICT   — 应用裁决 + 插入命令                  PERSIST: session.steps[], session.passed_gates[]
+S_AMEND_GOAL      — 修改 running session 目标               PERSIST: session.task_decomposition, .boundary_contract, .goal_changelog, .steps[]
 S_FALLBACK        — 请求用户输入                         PERSIST: —
 </states>
 
@@ -108,6 +114,8 @@ S_FALLBACK        — 请求用户输入                         PERSIST: —
 S_PARSE_ROUTE:
   → S_STATUS        WHEN: intent == "status"
   → S_CONTINUE      WHEN: intent == "continue"
+  → S_AMEND_GOAL    WHEN: amend_mode == true AND running session exists
+  → S_FALLBACK      WHEN: amend_mode == true AND no running session  DO: Display: "无 running session，--amend 需要活跃 session"
   → S_DECISION_EVAL WHEN: running session with decision step in "running" status
   → S_RESOLVE_PHASE WHEN: intent is non-empty                  ← phase 必须先于 position
   → S_FALLBACK      WHEN: no intent AND no running session
@@ -168,6 +176,8 @@ S_DECISION_EVAL: (decision 节点 == `step.decision` 非空，下述 gate 名取
                      DO: A_GOAL_AUDIT_EVALUATE
   → S_APPLY_VERDICT WHEN: scope-gate (post-analyze-scope)
                      DO: A_SCOPE_EVALUATE
+  → S_APPLY_VERDICT WHEN: reground-gate (post-reground)
+                     DO: A_REGROUND_EVALUATE
   → S_APPLY_VERDICT WHEN: structural (post-milestone, post-debug-escalate)
                      DO: A_STRUCTURAL_EVALUATE
 
@@ -182,12 +192,21 @@ S_APPLY_VERDICT:
   → END             WHEN: post-milestone + standard + no next milestone DO: mark completed
   → END             WHEN: post-milestone + adhoc                       DO: mark completed (adhoc self-contained)
   → END             WHEN: post-debug-escalate (always STOP)  DO: A_PAUSE_ESCALATE
+  → END             WHEN: post-reground + drifted + confidence_score >= 60  DO: A_REGROUND_HALT
+  → S_DISPATCH      WHEN: post-reground + aligned                           DO: A_APPLY_PROCEED
+  → S_DISPATCH      WHEN: post-reground + drifted + confidence_score < 60   DO: A_APPLY_PROCEED (标 LOW CONFIDENCE)
+  GUARD: post-reground + drifted + confidence_score >= 60 → A_REGROUND_HALT（漂移熔断，auto_confirm 不跳过）
   GUARD: retry_count >= max_retries → force escalate
   GUARD: confidence_score < 60 AND proceed → override to fix
   GUARD: confidence_score > 95 AND fix AND retry > 0 → suggest proceed
   GUARD: auto_confirm → skip user prompt, apply adjusted verdict
   GUARD: not auto_confirm → request_user_input with override options
 
+S_AMEND_GOAL:
+  → S_DISPATCH      WHEN: change applied + user confirmed    DO: A_AMEND_GOAL
+  → END             WHEN: user cancels
+  GUARD: RISK_LEVEL=high → auto_confirm 无效，强制用户确认
+
 S_FALLBACK:
   → S_PARSE_ROUTE   WHEN: user provides input               DO: request_user_input
   → END             WHEN: user cancels
@@ -244,7 +263,7 @@ resolve_milestone(phase_number):
 
 | Pattern | Position |
 |---------|----------|
-| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时跳过，直接 `brainstorm`**） |
+| 压力测试 / 拷问 / 验证假设 / grill / stress-test | `grill`（**auto_confirm=true 时透传 `-y`，grill Auto mode 代码代答，不跳过**） |
 | brainstorm / 头脑风暴 / 探索 / ideate / 设计思路 | `brainstorm` |
 | blueprint / 规格 / 正式文档 / spec-generate / 7-phase | `blueprint` |
 | broad/medium intent 无数字 phase (重构/全面/重写/迁移/新功能 X) | `analyze-macro` |
@@ -381,7 +400,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
 
 | Stage | Skill (independent) | Skill (unified) | Decision after | quality_mode |
 |-------|---------------------|-----------------|----------------|--------------|
-| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**skip when auto_confirm**) |
+| grill | `maestro-grill "{intent}"` | *(same)* | — | all (**auto_confirm → 透传 `-y`，不跳过**) |
 | brainstorm | `maestro-brainstorm "{intent}" --from grill:{grill_id}` *(if grill ran)* / `maestro-brainstorm "{intent}"` *(otherwise)* | *(same)* | — | all |
 | blueprint | `maestro-blueprint "{intent}"` | *(same)* | — | all |
 | init | `maestro-init` | *(same)* | — | all |
@@ -406,9 +425,14 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
 1. **起点**：从 `session.lifecycle_position` 开始
 2. **跳过已完成**：跳过当前 milestone+phase 下已有 completed artifact 的 stage（按 `session.phase` 过滤）；unified 按 milestone 过滤
 3. **quality_mode 过滤**：按 `session.quality_mode` 排除不匹配 stage
-3.5. **grill auto_confirm 跳过**：`auto_confirm == true` 时删除 `grill` stage（grill 为交互式苏格拉底拷问，不支持自动模式）；brainstorm args 不含 `--from grill:*`
+3.5. **grill auto_confirm 透传**：`auto_confirm == true` 时为 `grill` step args 追加 `-y`（grill 自身 Auto mode 用代码代答）；保留 `grill` stage 与 brainstorm 的 `--from grill:*`
 4. **决策节点**：每个 Decision after 非空的 stage 之后插入 `{ decision: "<gate>", retry_count: 0, max_retries: 2, command_scope: null, command_path: null }`
 5. **goal-audit 插入**：`task_decomposition` 存在时，在最后一个 evidence-producing stage（verify/review/test）之后、`milestone-complete` 之前插入 `decision:post-goal-audit`
+5.5. **re-grounding 插入**：WHEN `task_decomposition` 存在 AND 执行 step（不含 decision）≥3
+   - 从第 3 个执行 step 起每隔 3 个插入 `{ decision: "post-reground", retry_count: 0, max_retries: 0, command_scope: null, command_path: null }`
+   - 不在最后一个执行 step 后插入（由 goal-audit 覆盖）
+   - 不与已有 quality-gate decision 节点相邻（顺延到下一个 3-step 边界）
+   - fix-loop 动态插入的 step **纳入**计数（从插入点起重新计算 3-step 间隔）
 6. **终点硬约束**：`session.milestone` 存在时 chain 以 `milestone-complete` 结尾；`session.milestone=null`（standalone）时跳过 `milestone-audit` + `milestone-complete` stage，chain 以最后一个质量门 stage 结尾
 7. **goal_ref 传播**：`task_decomposition` 存在时，每个 step 按 `step.stage ∈ g.lifecycle` 匹配 `step.goal_ref = g.id`（多匹配取字典序最小）；decision 节点不打 goal_ref
 8. **占位符**：independent 保留 `{phase}` `{intent}`；unified 不带 `{phase}`
@@ -418,7 +442,7 @@ Generate steps from `session.lifecycle_position` to `milestone-complete`（`sess
      - 命中 → `command_scope = "global" | "project"`，`command_path = <绝对 SKILL.md 路径>`
      - 未命中 → `command_scope = "missing"`, `command_path = null`，A_CREATE_SESSION 报错 E006
    - **不在 build 阶段读取 SKILL.md 内容**；`<required_reading>` / `<deferred_reading>` 解析与加载由 `maestro ralph next` CLI 在执行期完成
-10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `deferred_reads: []`, `load: null`（由 `ralph next` 写入）
+10. **每个 step 初始化** `completion_confirmed: false`, `completion_status: null`, `completion_evidence: null`, `completion_summary: null`, `completion_decisions: null`, `completion_caveats: null`, `completion_deferred: null`, `deferred_reads: []`, `load: null`（由 `ralph next` 写入）
 11. **scope_verdict gating**（仅当 chain 起点 = `analyze-macro`）：
     - `scope_verdict ∈ {medium, small}` → 跳过 `roadmap` + `analyze` 两 stage；`plan` 选 standalone 列（`--from analyze:{analyze_macro_id}`），不带 `{phase}`
     - `scope_verdict == large` → 保留 `roadmap` + `analyze`；`plan` 选 phase 列（`{phase}`）
@@ -582,12 +606,85 @@ Runs only when `task_decomposition` present.
 2. Insert full lifecycle steps for next milestone
 3. Reindex, write status.json
 
+### A_REGROUND_EVALUATE
+
+GUARD: `task_decomposition` 存在（周期触发，见 build rule 5.5）
+
+1. Read status.json：
+   - `session.intent`, `session.boundary_contract`
+   - `steps[]` WHERE `status=="completed"` → 取 `completion_evidence`, `completion_summary`, `completion_decisions`, `completion_caveats`
+   - `task_decomposition[]` WHERE `status=="done"` → 取 `goal`, `done_when`
+2. Delegate read-only audit (run_in_background, STOP, wait):
+   ```
+   maestro delegate "PURPOSE: 意图保真检查 — 对照 intent 验证累积执行是否漂移
+   TASK:
+     1. 读取 intent + boundary_contract.definition_of_done
+     2. 读取已完成 steps 的 completion_summary + completion_decisions
+     3. 判定累积产出是否仍服务 intent；是否有 step 产出超出 in_scope 或触碰 out_of_scope
+     4. 输出 aligned / drifted
+   CONTEXT:
+     intent             = {session.intent}
+     definition_of_done = {boundary_contract.definition_of_done}
+     in_scope           = {boundary_contract.in_scope}
+     out_of_scope       = {boundary_contract.out_of_scope}
+     completed_steps    = [{index, skill, stage, completion_evidence, completion_summary, completion_decisions, completion_caveats}, ...]
+     done_goals         = [{id, goal, done_when}, ...]
+     accumulated_deferred = [{from_step, item}, ...]
+     goal_changelog     = {session.goal_changelog ?? []}
+   EXPECTED:
+     ---VERDICT---
+     STATUS=aligned|drifted
+     DRIFT_DESCRIPTION=<空或具体描述>
+     CORRECTIVE_ACTION=<空或建议>
+     CONFIDENCE_SCORE=0-100
+     ---END---
+   CONSTRAINTS:
+     - 只评估不修改
+     - aligned 阈值：≥80% 已完成产出直接服务 intent
+     - 单个 step 触碰 out_of_scope → 直接判 drifted
+     - goal_changelog 存在 → 以最新 after.goals 为基准"
+   --role analyze --mode analysis
+   ```
+3. On callback: parse verdict
+4. Append `{session_dir}/decisions.ndjson`：`{ "id": "DEC-{ts}", "type": "reground-gate", "source": "ralph", "node_id": "post-reground", "verdict": "{aligned|drifted}", "confidence_score": {N} }`
+5. Verdict routing：`aligned` → A_APPLY_PROCEED；`drifted` + `confidence_score >= 60` → A_REGROUND_HALT；`drifted` + `confidence_score < 60` → A_APPLY_PROCEED（标 LOW CONFIDENCE）
+
+### A_REGROUND_HALT
+
+漂移熔断（安全门，auto_confirm 不跳过）。
+
+1. Set `session.status = "paused"`，write status.json
+2. Display:
+   ```
+   ⚠️ Re-grounding 检测失败 — 执行已偏离 intent。
+   Intent: {session.intent}
+   Drift:  {drift_description}
+   建议回归: {corrective_action}
+   选项：1) $maestro-ralph continue 忽略漂移继续  2) 手动修正后 continue  3) $maestro-ralph status 查看后决定
+   ```
+3. GUARD: auto_confirm 对本动作无效——漂移熔断不可自动跳过
+
 ### A_PAUSE_ESCALATE
 
 1. Set session status = "paused", write status.json
 2. Display: ◆ 已达最大重试次数，debug 已执行。请人工介入。
 3. Display: $maestro-ralph continue 恢复
 
+### A_AMEND_GOAL
+
+修改 running session 目标。详细流程由 `<deferred_reading>` 加载 `ralph-amend-goal.md`。
+
+| Phase | 行为 | 产出 |
+|-------|------|------|
+| 1. 快照 | 读 `task_decomposition` + `boundary_contract` + 已完成 steps 的 `completion_summary` | Display: 目标列表 + 进度 |
+| 2. 解析 | `change_request` 非空 → 直接用；为空 → request_user_input（修改/新增/移除/调整边界） | `change_type` + `change_request` |
+| 3. Mini Grill | `maestro delegate --role analyze --mode analysis`：评估影响 | RISK_LEVEL + AFFECTED_GOALS + INVALIDATED_STEPS + NEW_GAPS |
+| 4. 确认 | request_user_input：应用并继续 / 仅改目标 / 取消 | 用户选择 |
+| 5. 应用 | 归档旧目标（`superseded`）→ 写入新目标（`origin: CHG-xxx`）→ 重建链路 → write status.json | handoff $maestro-ralph-execute |
+
+GUARD: `RISK_LEVEL == high` → request_user_input 不跳过（auto_confirm 无效）
+GUARD: 已完成（`status: "done"`）的目标不可 supersede（skip + warn）
+
 </actions>
 
 </state_machine>
@@ -600,7 +697,7 @@ Runs only when `task_decomposition` present.
 {
   "session_id": "ralph-{YYYYMMDD-HHmmss}",
   "source": "ralph", "status": "running",
-  "ralph_protocol_version": "1",   // CLI-driven; absent/0 → legacy inline ralph-execute
+  "ralph_protocol_version": "2",   // CLI-driven; absent/0 → legacy; "1" → basic CLI; "2" → structured completion + enhanced anchor
   "active_step_index": null,       // CLI-managed; only one step held at a time
   "intent": "", "lifecycle_position": "",
   "phase": null, "phase_is_new": false,
@@ -634,6 +731,10 @@ Runs only when `task_decomposition` present.
     "completion_confirmed": false,
     "completion_status": null,
     "completion_evidence": null,
+    "completion_summary": null,      // 一句话总结：做了什么（MUST on DONE）
+    "completion_decisions": null,    // 本 step 做出的关键决策列表
+    "completion_caveats": null,      // 后续 step 需注意的事项
+    "completion_deferred": null,     // 被推迟到后续的工作列表
     "completed_at": null,
     "deferred_reads": [],         // 由 ralph next CLI 解析 SKILL.md 时填充
     "load": null                  // { loaded_at, required_files[], deferred_files[], resolve_version } —— 由 ralph next 写入
@@ -647,10 +748,22 @@ Runs only when `task_decomposition` present.
   "execution_criteria": [],
   "task_decomposition": [
     { "id": "G1", "goal": "", "boundary": "", "done_when": "",
-      "evidence": "", "lifecycle": [], "status": "pending|done",
-      "completion_confirmed": false, "completed_at": null }
+      "evidence": "", "lifecycle": [], "status": "pending|done|superseded",
+      "completion_confirmed": false, "completed_at": null,
+      "superseded_by": null, "superseded_at": null, "origin": null }
   ],
-  "task_decomposition_all_done": false
+  "task_decomposition_all_done": false,
+
+  // goal_changelog: additive; absent → no amendments
+  "goal_changelog": [
+    { "id": "CHG-001", "timestamp": "{ISO}",
+      "change_type": "modify|add|remove|boundary",
+      "reason": "变更描述",
+      "impact_assessment": { "risk_level": "low|medium|high",
+        "invalidated_steps": [], "new_steps_inserted": 0 },
+      "before": { "goals": [{"id":"G1","goal":"...","done_when":"..."}] },
+      "after":  { "goals": [{"id":"G1v2","goal":"...","done_when":"..."}] } }
+  ]
 }
 ```
 
@@ -744,7 +857,7 @@ decision:post-goal-audit {retry+1}
 - [ ] D-007 反查：phase 数字 → `session.milestone`，禁止读 current_milestone；写入 step.milestone_id
 - [ ] phase_is_new=true → lifecycle_position 强制 `analyze`
 - [ ] Intent overrides 识别 grill / brainstorm / blueprint / analyze-macro
-- [ ] auto_confirm=true 时 grill stage 跳过（交互式拷问不支持自动模式）
+- [ ] auto_confirm=true 时 grill step args 追加 `-y`（Auto mode 代码代答，stage 不跳过）
 - [ ] A_RESOLVE_SCOPE_VERDICT 读 macro analyze conclusions.scope_verdict，写入 session.scope_verdict + analyze_macro_id
 - [ ] 链路起点 = analyze-macro 时：large→roadmap+analyze+plan(phase)；medium/small→直跳 plan --from analyze:{ANL_ID}（跳过 roadmap+analyze）
 - [ ] post-analyze-scope decision 节点在 macro analyze 之后插入；A_SCOPE_EVALUATE/A_APPLY_SCOPE_VERDICT 重塑链路
@@ -768,5 +881,19 @@ decision:post-goal-audit {retry+1}
 - [ ] Phase-level deferred chaining：plan/execute step 的 `--from`/`--dir` 注入由 A_RESOLVE_ARGS（ralph-execute）运行时完成；build 阶段标记意图，不预知 artifact ID
 - [ ] Phase-level plan step 运行时获得 `--from analyze:{phase_analyze_id}`（由 ralph-execute 从 state.json 查找注入）
 - [ ] Phase-level execute step 运行时获得 `source_artifact_ref = "plan:{id}"`
+- [ ] 每个 step 含 `completion_summary` + `completion_decisions` + `completion_caveats` + `completion_deferred`（初始 null）
+- [ ] `completion_summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（由 CLI `--summary` 参数传入）
+- [ ] session_anchor 包含最近 5 个已完成 step 的 `completion_summary` + `completion_caveats`（滑动窗口）
+- [ ] session_anchor 包含 task_decomposition 全局视图（仅 `status != "superseded"` 的目标）
+- [ ] session_anchor 包含 Accumulated Signals（聚合所有 caveats + deferred）
+- [ ] `--amend` 路由到 S_AMEND_GOAL（需 running session）
+- [ ] A_AMEND_GOAL 执行 5 阶段（快照→解析→mini grill→确认→应用），每阶段产出可审计
+- [ ] 旧目标标 `superseded`（`superseded_by` + `superseded_at`），新目标标 `origin: "CHG-xxx"`
+- [ ] `goal_changelog` 记录完整 before/after 快照 + impact_assessment
+- [ ] `RISK_LEVEL=high` 时 amend 不跳过 auto_confirm
+- [ ] re-grounding 完成 steps 信息含 completion_summary/decisions/caveats
+- [ ] fix-loop 动态插入 step 纳入 re-grounding 3-step 计数
+- [ ] post-reground + drifted + confidence >= 60 → A_REGROUND_HALT（auto_confirm 不跳过）
+- [ ] session_anchor boundary_contract 不截断（capAnchorList n=8）
 
 </appendix>

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

@@ -181,7 +181,9 @@ Write enriched args + source_artifact_ref back to status.json.
    - 退出码 2 → 交给 S_LOCATE
    - 退出码 3 → active_step_index 已被占用
    - 退出码 1 → pause session
-2. **Goal context pre-injection** — 若 A_RESOLVE_ARGS 产出了 `goal_snippet`（step.goal_ref 非空），在 ralph next stdout prompt **顶部前置**以下 block，使执行命令感知当前子目标和执行约束：
+2. **Goal context pre-injection**:
+   - GUARD: `ralph_protocol_version >= "2"` → skip（session_anchor 已含 goal context）
+   - WHEN `ralph_protocol_version < "2"` 或缺失 AND `step.goal_ref` 非空 → 在 stdout 顶部前置：
    ```
    <goal_context>
    Sub-goal: {goal.id} — {goal.goal}
@@ -191,13 +193,19 @@ Write enriched args + source_artifact_ref back to status.json.
    Execution criteria: {session.execution_criteria joined by '; '}
    </goal_context>
    ```
-   无 goal_snippet 时跳过此步。goal_context block 不替换 ralph next 的 stdout 内容，仅在其前方拼接。
-3. **Inline execution** — 按 stdout（含 goal_context 前置）执行；deferred_reading 按需 Read
+3. **Inline execution** — 按 stdout 执行；deferred_reading 按需 Read
 4. **Complete**:
-   - `Bash("maestro ralph complete N --status DONE [--evidence <path>]")`
-   - `Bash("maestro ralph complete N --status DONE_WITH_CONCERNS --concerns \"...\"")`
+   - `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 \"...\"")`
+
+   | Flag | 规则 | 示例 |
+   |------|------|------|
+   | `--summary` | MUST。动词开头，≤100 字 | `"实现搜索 API 分页，新增 3 端点"` |
+   | `--decisions` | SHOULD。每条一个决策，可多次 | `"选择 ELK 而非 dagre"` |
+   | `--caveats` | SHOULD。后续 step 需注意 | `"e2e 未覆盖新端点"` |
+   | `--deferred` | SHOULD。推迟工作，可多次 | `"性能优化留到 review 后"` |
 5. **Propagate context signals** — 关键信号 (`PHASE: N` / `scratch_dir: path` / `BLP-xxx`) 写入 `status.json.context`
 
 完成后 S_LOCATE 触发 `$maestro-ralph-execute` 直调自调用。
@@ -278,8 +286,11 @@ Display: `[{index}/{total}] ✗ {step.skill} 失败，会话已暂停。$maestro
 - [ ] 只处理 session.platform == "codex" 的会话
 - [ ] --from auto-injection：phase-level plan step 运行时从 state.json 查找同 phase+milestone 最新 completed analyze artifact → 注入 `--from analyze:{id}`，写 `source_artifact_ref`
 - [ ] --from auto-injection：phase-level execute step 运行时查找同 phase+milestone 最新 completed plan artifact → 注入 `--dir`，写 `source_artifact_ref`
-- [ ] Goal context injection：step.goal_ref 非空时从 task_decomposition 提取 goal_snippet，A_EXEC_STEP 在 ralph next stdout 顶部前置 `<goal_context>` block
+- [ ] Goal context injection：`ralph_protocol_version < "2"` → 前置 `<goal_context>` block；`>= "2"` → skip（session_anchor 覆盖）
 - [ ] Goal context 包含 sub-goal description、done_when、boundary、evidence、execution_criteria
 - [ ] 已有 `--from` 或 `--dir` 的 step 不被 auto-injection 覆盖
+- [ ] `--summary` 在 DONE/DONE_WITH_CONCERNS 时为 MUST（动词开头，≤100 字）
+- [ ] `--decisions`/`--caveats`/`--deferred` 为 SHOULD；存在关键决策/注意事项/推迟工作时填写
+- [ ] 结构化总结由 CLI 写入 status.json，session_anchor 自动聚合注入下游 step
 
 </appendix>

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

@@ -29,7 +29,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 **Output**: tasks.csv, results.csv, discoveries.ndjson, context.md, `.workflow/roadmap.md`
 
 ### Pre-load (runs unconditionally, including -y auto mode)
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+1. **Architecture specs**: `maestro load --type spec --category arch` — load architecture constraints for phase decomposition
 2. **Wiki search**: `maestro search "{requirement keywords}" --json` → prior knowledge for dependency and scope analysis
 3. All optional — proceed without if unavailable (log warning)
 </context>
@@ -38,7 +38,7 @@ $ARGUMENTS -- requirement/idea text or @file reference, plus optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c`, or input is already specific (clear requirement + mode).
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately appended/updated in the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.

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

@@ -33,13 +33,13 @@ Empty arguments enters interactive mode: list all tools for user selection.
 
 **By name**:
 ```bash
-maestro spec load --category coding --keyword <name>
+maestro load --type spec --category coding --keyword <name>
 ```
 Match tool entries whose title or keywords contain the name.
 
 **By category**:
 ```bash
-maestro spec load --category <category>
+maestro load --type spec --category <category>
 ```
 Extract tool entries from output, list available tools.
 
@@ -54,7 +54,7 @@ Show tool information:
 
 Expand ref entries:
 ```bash
-maestro wiki load <knowhow-id>
+maestro load --type knowhow --id <knowhow-id>
 ```
 
 ### Step 3: Confirm Execution