maestro-flow 0.5.37 → 0.5.39

package/workflows/debug.md

@@ -110,6 +110,7 @@ If resuming: load understanding.md + evidence.ndjson, spawn continuation agent.
 ### Step 1.5: Load Project Specs
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_content = maestro spec load --category debug
 → Pass to debug agents as prior knowledge
 ```
@@ -175,7 +176,7 @@ Create the directory.
 
 ---
 
-### Step 5: Spawn Parallel Debug Agents
+### Step 5: Spawn Parallel Debug Agents — MANDATORY, NOT SUBSTITUTABLE
 
 For each cluster, spawn concurrently (`run_in_background: false`):
 
@@ -219,7 +220,7 @@ Pass cli_evidence as supplementary_context to debug agent prompts in Step 5/6
 
 ---
 
-### Step 6: Spawn Single Debug Agent (sequential mode)
+### Step 6: Spawn Single Debug Agent (sequential mode) — MANDATORY, NOT SUBSTITUTABLE
 
 Spawn agent (`run_in_background: false`):
 
@@ -330,6 +331,8 @@ Load prior state (understanding.md + evidence.ndjson) + user checkpoint response
 
 ---
 
+**GATE Step 12→13**: Glob `{$DEBUG_DIR}/understanding.md` AND `{$DEBUG_DIR}/evidence.ndjson` MUST exist before Step 13 report; BLOCKED if missing.
+
 ### Step 13: Report
 
 ```

package/workflows/domain-add.md

@@ -56,6 +56,7 @@ Auto-derive from the definition and codebase context:
 Write via `maestro domain add`:
 
 ```bash
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 maestro domain add "<canonical>" "<definition>" --tier <tier>
 ```
 
@@ -67,11 +68,14 @@ maestro domain update "<canonical>" --aliases "alias1,alias2" --keywords "kw1,kw
 
 Records `source.kind = 'manual'`, `source.registered_at = now`.
 
+**GATE Step 4→5**: REQUIRED term written via `maestro domain add` (exit 0); BLOCKED if write failed or term missing from glossary.
+
 ### Step 5: Verify Injection
 
 Confirm the term is injectable by checking:
 
 ```bash
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 maestro domain show "<canonical>"
 ```
 
@@ -80,6 +84,8 @@ Display: canonical name, definition, aliases, tier, relationships, and verify co
 maestro domain list
 ```
 
+**GATE Step 5→6**: REQUIRED term verified injectable via `maestro domain show`; BLOCKED if not injectable.
+
 ### Step 6: Report
 
 ```

package/workflows/drift-realign.md

@@ -0,0 +1,396 @@
+# Drift Realign Workflow
+
+---
+
+## Prerequisites
+
+- `.workflow/` 已初始化（`.workflow/state.json` 存在）
+- Git 仓库可访问（`git log` 可执行）
+- 至少一个 `.workflow/` artifact 存在
+- REQUIRED: wiki indexed via `maestro wiki rebuild` (supports session association)
+
+
+---
+
+## Argument Shape
+
+```
+/drift-realign --scope all                          → 全量扫描所有 scope（交互式）
+/drift-realign --scope spec --since 2026-06-01      → 仅扫 spec 漂移，指定起始时间
+/drift-realign --scope roadmap --depth deep          → 深度扫描 roadmap
+/drift-realign --scope all --dry-run                 → 完整预演，不写盘
+/drift-realign --scope all --report                  → 仅出报告不动盘
+/drift-realign --scope codebase --auto-archive       → 自动归档 codebase 漂移
+/drift-realign --scope all --interactive             → 逐条交互决策
+```
+
+| Flag | Effect |
+|------|--------|
+| `--scope <type>` | 目标 scope: roadmap / spec / codebase / state / issue / knowhow / project / all（默认 all） |
+| `--since <date\|commit>` | 起始时间点（日期或 commit hash），覆盖自动推断 |
+| `--depth <level>` | shallow（正则 + 路径校验）/ deep（LLM 语义分析），默认 shallow |
+| `--dry-run` | 全流程预演，展示所有 findings 和建议 action，不写盘 |
+| `--report` | 仅生成报告到 `.workflow/.drift-realign/`，跳过交互和 apply |
+| `--auto-archive` | P1/P2 自动归档，P0 保留人工审查 |
+| `--interactive` | 逐条交互决策（默认开启，除非 `--report` 或 `--auto-archive`）|
+
+互斥规则：`--report` 强制 read-only，覆盖其他 mode；`--auto-archive` 与 `--interactive` 互斥；`--auto-archive` 覆盖 `--interactive`。
+
+---
+
+## Stage 1: parse_input
+
+```
+验证 .workflow/ 存在（否则 E001）。解析参数：
+  scope: roadmap | spec | codebase | state | issue | knowhow | project | all（默认 all，E002 若非法值）
+  since: 显式指定 → 使用提供的日期/commit
+         state.json.last_drift_realign 存在 → 使用该值
+         state.json.last_pruned 存在 → 使用该值
+         兜底 → 90 天前
+  depth: shallow（默认）| deep
+  mode: interactive（默认）| dry-run | report | auto-archive
+
+互斥校验：
+  --report → 强制覆盖 mode 为 read-only
+  --auto-archive 覆盖 --interactive（非错误，静默降级）; flag session as [LOW CONFIDENCE] (interactive skipped)
+
+检查 git 可用性（E003）。
+初始化 .workflow/.drift-realign/ 目录。
+```
+
+---
+
+## Stage 2: reconstruct_timeline
+
+```
+运行 maestro timeline --since <resolved_date> --json --output .workflow/.drift-realign/timeline-{date}.json
+
+timeline 每条 session 事件包含以下字段（已足够 shallow 分析）：
+  id:           session 唯一标识
+  title:        session 标题
+  summary:      用户首条提问摘要（≤200 字符）
+  edited_files: 该 session 编辑的文件列表
+  code_paths:   该 session 涉及的代码路径
+  platform:     平台标识（claude / codex / unknown）
+
+解析输出提取以下结构：
+  window: { from, to, total_days }
+  git_summary: { commit_count, files_changed, insertions, deletions }
+  session_summary: { total, with_edits, last_session_date, by_platform: { claude: N, codex: N, ... } }
+  events: 按时间戳排序的 commit + session 事件交织列表
+  hot_paths: 变更频率最高的目录列表（包含 git files + session edited_files + code_paths）
+  cold_workflow_files: 在窗口内未修改的 .workflow/ 文件列表
+```
+
+### 2a. 平台问询（交互式）
+
+```
+检查 session_summary.by_platform 分布。
+如果存在多个平台且 session 总量 > 20：
+  使用 AskUserQuestion 向用户展示平台分布并询问：
+    "检测到多个 session 平台（claude: 80, codex: 40, unknown: 12）。
+     修改主要在哪个平台进行？聚焦特定平台可以缩小分析范围。"
+    选项:
+      - 全部平台（不过滤）
+      - Claude（仅 Claude Code session）
+      - Codex（仅 Codex session）
+
+  如果用户选择特定平台：
+    重新运行 maestro timeline --since <date> --platform <选择> --json --output ...
+    后续 scanner agent 仅使用该平台的 session 上下文。
+```
+
+### 2b. Session 详情按需加载
+
+```
+timeline 事件中的 summary + edited_files + code_paths 足以支撑 shallow 扫描。
+当 --depth deep 时，scanner agent 可能需要 session 完整内容来判断语义漂移：
+
+  对于与 drifted .workflow/ 文件有交集的 session（edited_files 交集检测）：
+    maestro load --type session --id <session_id> --json
+    → 获取 body（详细描述）、related（关联条目）等完整字段
+
+  按需加载规则：
+    1. 仅 --depth deep 时触发
+    2. 仅加载 edited_files 与 cold_workflow_files 有交集的 session
+    3. 最多加载 10 个 session（按相关度排序：交集文件数降序）
+    4. 加载结果写入 .workflow/.drift-realign/session-details-{date}.json
+    5. scanner agent 在 deep 模式下同时接收 timeline.json + session-details.json
+```
+
+---
+
+## Stage 3: compute_drift_score
+
+```
+公式：drift_score = drift_window_days × sqrt(changed_files_count) × scope_weight
+
+changed_files_count 来源：git_summary.files_changed + session 中 edited_files 去重后的独立文件数。
+合并公式：changed_files_count = |Set(git_files) ∪ Set(session_edited_files)|
+
+scope_weight 映射：
+  roadmap:  1.5  （结构性，影响所有下游）
+  spec:     1.3  （影响编码指导）
+  project:  1.4  （基础性）
+  state:    1.2  （运行态）
+  codebase: 1.0  （文档）
+  issue:    0.8  （跟踪）
+  knowhow:  0.7  （参考）
+
+阈值判定：
+  LOW:      score < 30   → 以 --depth shallow 继续
+  MODERATE: 30 ≤ score < 100 → 以配置的 depth 继续
+  SEVERE:   score ≥ 100  → 自动升级为 --depth deep，若 drift_window > 180 天则 emit W002
+
+向用户展示 drift summary。
+```
+
+---
+
+## Stage 4: parallel_drift_scan
+
+**MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 在单条消息中并行派发 4 个 agent。每个 agent 接收 timeline.json + 相关 scope 文件 + git diff 摘要。**
+
+### 4a. roadmap-scanner
+
+| Drift Type | Detection Algorithm | Severity |
+|-----------|-------------------|----------|
+| phantom_phase | roadmap.md 列出的 phase 在代码或 state.json 中无对应 | P0 |
+| stale_progress | Phase Progress 表格百分比与实际 task 完成状态不符 | P1 |
+| milestone_mismatch | state.json milestones 与 roadmap.md milestone 描述不一致 | P0 |
+| outdated_criteria | 成功标准引用了已删除/重命名的 feature | P1 |
+| dependency_ghost | 依赖引用指向已删除/重构的模块 | P1 |
+| timeline_impossible | roadmap 中的日期已过期但 milestone 未标记完成 | P2 |
+
+### 4b. spec-scanner
+
+| Drift Type | Detection Algorithm | Severity |
+|-----------|-------------------|----------|
+| convention_violation | Spec 规定 "使用 X 模式" 但 git diff 显示代码使用 Y 模式 | P0 |
+| dead_import_pattern | Spec 引用的 import 风格在 codebase 中已不存在 | P1 |
+| architecture_breach | 新代码结构违反了架构约束 | P0 |
+| stale_dependency | Spec 提及的库版本/API 与 package.json 矛盾 | P1 |
+| naming_drift | Spec 中的命名规范与 hot_paths 实际命名不匹配 | P2 |
+| test_convention_gap | 测试规范 spec vs 实际测试文件模式 | P2 |
+
+检测方法：
+- shallow：grep spec 引用的模式匹配 hot_paths 文件，检查文件是否存在
+- deep：LLM 阅读 spec entry + hot_paths 代码采样，判断对齐度
+
+### 4c. codebase-scanner
+
+| Drift Type | Detection Algorithm | Severity |
+|-----------|-------------------|----------|
+| architecture_outdated | architecture.md 描述的结构已被 git diff 改变 | P0 |
+| feature_missing | features.md 未提及近期 commit 中可见的新 feature | P1 |
+| tech_stack_changed | tech-stack.md 列出已移除的依赖或遗漏新增依赖 | P0 |
+| concern_drift | concerns.md 描述的模式已不存在 | P1 |
+| doc_index_stale | doc-index.json 引用的文件在磁盘上不存在 | P0 |
+
+检测方法：
+- shallow：交叉校验 doc-index.json 路径与文件系统，检查文件 mtime
+- deep：LLM 阅读每个 codebase 文档 + 采样近期代码，判断准确性
+
+### 4d. artifact-scanner
+
+| Drift Type | Detection Algorithm | Severity |
+|-----------|-------------------|----------|
+| issue_code_ref_dead | issues.jsonl 的 related_files 指向已移动/删除的路径 | P1 |
+| issue_stale_open | Open issue 的 fix_direction 引用了已重构的代码 | P1 |
+| knowhow_code_ref_dead | Knowhow entry 引用的代码路径已不存在 | P1 |
+| orphan_session | active/ 中的 session 在 state.json 中无对应 artifact | P2 |
+| project_tech_drift | project.md Tech Stack 部分 vs 实际 package.json/code | P0 |
+| project_req_drift | project.md Requirements 部分 vs 已实现的 feature | P1 |
+| accumulated_stale | state.json accumulated_context.key_decisions 引用已重构区域 | P1 |
+| deferred_resolved | state.json deferred items 实际已被 git 历史证明已实现 | P2 |
+
+每个 agent 返回：
+```
+DriftFinding {
+  id: "DFT-{8hex}",
+  scope: "roadmap" | "spec" | "codebase" | "state" | "issue" | "knowhow" | "project",
+  severity: "P0" | "P1" | "P2",
+  target: { file: string, section?: string },
+  drift_type: string,
+  evidence: { code_reality: string, doc_claim: string, git_ref?: string },
+  suggested_action: "keep" | "update" | "archive" | "rebuild",
+  update_hint?: string
+}
+```
+
+---
+
+## Stage 5: synthesize_findings
+
+```
+合并所有 agent 结果为统一 DriftFinding[]。
+
+去重：若多个 agent 标记同一 file+section，保留最高 severity。
+排序：P0 优先，然后 P1，然后 P2。
+按 --scope 过滤（若非 "all"）。
+按 scope 和 severity 统计计数。
+
+Conflict-marker 集成：
+  MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 运行 maestro spec conflict list → 已标记的冲突条目
+  对于已有 conflict-marker 的 spec 条目，若 drift scanner 也检测到同一文件：
+    合并为同一 finding（提升 severity 到 P0，来源标注 "drift + conflict-marker"）
+  对于 drift scanner 发现但无 conflict-marker 的条目：保持 scanner 原始 severity
+```
+
+---
+
+## Stage 6: interactive_triage
+
+```
+若 --report → 跳至 Stage 9。
+若 --auto-archive → 自动应用每个 finding 的 suggested_action（P1/P2 直接执行，P0 保留人工审查）。
+若 --dry-run → 展示所有 findings 及建议 action，跳过 Stage 7-8。
+
+否则，逐条交互：
+```
+
+```
+[!] Drift Detected (P0 - architecture_outdated)
+Scope:    codebase
+Target:   .workflow/codebase/architecture.md §Module Boundaries
+Evidence: Code added new src/payments/ module not described in architecture.md
+Git Ref:  commit abc123 (2026-06-10)
+Hint:     Add Payments module section describing src/payments/ structure
+Suggestion: [u]pdate
+
+Action?  [k]eep / [u]pdate / [a]rchive / [r]ebuild / [s]kip / [q]uit
+> _
+```
+
+| Action | 行为 |
+|--------|------|
+| `keep` | 确认无漂移或可接受，标记为已审查（记录到 drift-log.jsonl action=keep）|
+| `update` | 在目标文件顶部注入 TODO 标记：`<!-- DRIFT-TODO: {update_hint} (DFT-{id}, {date}) -->` |
+| `archive` | 移动到 .trash/（先备份）|
+| `rebuild` | 标记为自动重建目标（codebase scope 触发 `/quality-sync --full`）|
+| `skip` | 跳过本条不做决策（记录到 drift-log.jsonl action=skipped，下次 re-run 会重新出现）|
+
+---
+
+## Stage 7: backup
+
+```
+mkdir .workflow/.trash/drift-realign-{ISO_timestamp}/
+for each actionable finding:
+  cp target.file → .trash/{timestamp}/{relative_path}
+也备份 state.json → .trash/{timestamp}/state.json.bak
+若任一备份失败 → E005，禁止 Stage 8
+```
+
+---
+
+## Stage 8: apply_actions
+
+| Action | 实施 |
+|--------|------|
+| `keep` | 写 drift-log.jsonl 一条 action=keep 记录 |
+| `skip` | 写 drift-log.jsonl 一条 action=skipped 记录（不标记 reviewed，下次 re-run 重现）|
+| `update` | 在目标文件头部插入 TODO 注释块：`<!-- DRIFT-TODO: {update_hint} (DFT-{id}, {date}) -->` |
+| `archive` | 移动文件到 `.trash/{timestamp}/` + 更新 state.json 引用 |
+| `rebuild` | 收集 rebuild 目标；全部其他 action 完成后：通过 `Skill()` 自动调用 `/quality-sync --full` |
+
+rebuild 后处理：
+- 若 W001 或重大结构变更 → MUST run `/manage-codebase-rebuild`
+
+Conflict-marker 清除：
+- 对于 update/archive 的 spec 目标文件，若存在 conflict-marker：
+  maestro spec conflict clear <file> <line>
+  （与 knowledge-audit 的 deprecate/delete 清除行为对称）
+
+更新 state.json：设置 `last_drift_realign = now`（ISO-8601）
+
+state.json 原子写：备份 → 写新版本 → re-read 验证。
+
+---
+
+## Stage 9: report
+
+写 `.workflow/.drift-realign/drift-report-{date}.md`：
+
+```markdown
+# Drift Realign Report — {date}
+
+## Timeline Window
+- From: {from} → To: {to} ({days} days)
+- Git: {commits} commits, {files_changed} files changed
+- Sessions: {total} total, {with_edits} with edits
+- Drift Score: {score} ({LOW|MODERATE|SEVERE})
+
+## Scan Summary
+- Total findings: {N} ({P0} P0 / {P1} P1 / {P2} P2)
+- By scope: roadmap {N} / spec {N} / codebase {N} / state {N} / issue {N} / knowhow {N} / project {N}
+
+## Actions Applied
+| # | Scope | Drift Type | Target | Action | Status |
+|---|-------|-----------|--------|--------|--------|
+| 1 | codebase | architecture_outdated | architecture.md §Module Boundaries | update | OK |
+| 2 | spec | convention_violation | coding-conventions.md §Import Rules | archive | OK |
+
+## Kept (no drift or user chose keep)
+| Finding | Reason |
+|---------|--------|
+| DFT-abc12345 | User chose keep — marked as reviewed |
+
+## Auto-Rebuilt
+- /quality-sync --full triggered: {yes/no}
+- /manage-codebase-rebuild suggested: {yes/no}
+
+## Backup
+- Location: .workflow/.trash/drift-realign-{timestamp}/
+```
+
+同时追加结构化条目到 `.workflow/.drift-realign/drift-log.jsonl`（每行一条 JSON）：
+
+```json
+{
+  "realign_id": "DFT-RUN-{timestamp}",
+  "finding_id": "DFT-{8hex}",
+  "scope": "codebase",
+  "drift_type": "architecture_outdated",
+  "severity": "P0",
+  "target": { "file": ".workflow/codebase/architecture.md", "section": "Module Boundaries" },
+  "action": "update",
+  "applied_at": "2026-06-24T15:30:00.000Z",
+  "backup_path": ".workflow/.trash/drift-realign-20260624T153000/"
+}
+```
+
+显示摘要并引导后续步骤：
+
+```
+=== DRIFT REALIGN COMPLETE ===
+Scope: all
+
+  Findings:  18 total (4 P0 / 9 P1 / 5 P2)
+  Updated:   6 (TODO markers injected)
+  Archived:  3 (moved to .trash/)
+  Rebuilt:   2 (via /quality-sync --full)
+  Kept:      7 (marked as reviewed)
+
+  Report:  .workflow/.drift-realign/drift-report-2026-06-24.md
+  Backup:  .workflow/.trash/drift-realign-20260624T153000/
+
+Next:
+  → 处理 TODO 标记:           grep -r "DRIFT-TODO" .workflow/
+  → 内部矛盾审查:             /manage-knowledge-audit --scope all
+  → 全量 codebase 重建:       /manage-codebase-rebuild
+  → 周期巡检 (REQUIRED at milestone end): run --scope all --report
+```
+
+---
+
+### Safety invariants
+
+1. **Code-as-Truth** — 代码永远是对的；当代码和文档不一致时，是文档漂移了
+2. **Backup before mutate** — Stage 7 必须成功才能执行 Stage 8；state.json 原子写（备份 → 写新 → re-read 校验）
+3. **No auto-delete** — drift-realign 绝不物理删除文件；archive 仅移动到 `.trash/`
+4. **Rebuild is scoped** — 自动重建仅对 codebase scope 触发，绝不对 spec/roadmap 触发
+5. **Idempotent** — 相同输入产生相同 findings（git 状态 + 文件状态确定性）
+6. **Graceful degradation** — wiki/session 不可用时（W001），以 git-only timeline 继续; flag timeline as [LOW CONFIDENCE] (wiki/session unavailable)
+7. **Preserve user work** — TODO 标记是注释，绝不覆盖文件内容
+8. **State.json atomic** — 所有 state.json 变更遵循 备份 → 写新 → 验证 模式

package/workflows/execute.md

@@ -193,6 +193,7 @@ Build execution_queue from plan.json.waves, including only waves with pending (n
 ## E1.5: Load Project Specs
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_content = maestro spec load --category coding
 ```
 
@@ -316,7 +317,7 @@ Each task = one independent dispatch (never merge tasks into one delegate prompt
 ```
 Max 3 auto-fix attempts per task:
   Agent path: handled internally by workflow-executor agent
-  CLI path: 1) --resume ${fixedId} → 2) simplified prompt → 3) fallback to agent
+  CLI path: 1) --resume ${fixedId} → 2) simplified prompt → 3) fallback to agent; flag task as [LOW CONFIDENCE] (agent fallback used)
 
 If all 3 fail: mark "blocked" with checkpoint in .task/${task_id}.json.meta.checkpoint
   { attempt: 3, last_error, partial_files, executor, delegate_id: fixedId }
@@ -528,7 +529,7 @@ If config.json.codebase.auto_sync_after_execute == true:
     3. Update affected entries
     4. Refresh tech-registry and feature-maps as needed
 Else:
-  Log "Auto-sync disabled. Run /workflow:sync manually if needed."
+  Log "Auto-sync disabled. MUST run /workflow:sync manually."
 ```
 
 ---
@@ -608,8 +609,8 @@ Mark artifact.harvested = true; write state.json (atomic)
 | Plan directory not found | Abort: "Plan dir not found." |
 | Task file missing | Skip task, log error, continue wave |
 | Agent spawn fails | Retry once, then mark task as "blocked" |
-| Delegate fails | Resume with `--resume ${fixedId}`, then fallback to agent |
-| Git commit fails | Log warning, continue (task still marked completed) |
+| Delegate fails | Resume with `--resume ${fixedId}`, then fallback to agent; flag task as [LOW CONFIDENCE] (fallback agent) |
+| Git commit fails | Log W0xx, mark task [LOW CONFIDENCE] (commit failed); do NOT mark fully completed until commit succeeds |
 | All tasks in wave blocked | Stop execution, report blocked wave |
 
 ---

package/workflows/explore-usage.md

@@ -67,7 +67,7 @@ Endpoint B:  [job4] → [job5]              (serial)
                                            ↑ parallel ↑
 ```
 
-Raise per-endpoint parallelism with `--ep-concurrency 2` when the API allows it.
+Raise per-endpoint parallelism with `--ep-concurrency 2` when the API rate limit permits (verify via test request).
 
 ## Multi-Prompt Input
 
@@ -126,7 +126,7 @@ Multi-prompt — **background**:
 Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
 ```
 
-Single quick lookup — foreground is fine:
+Single quick lookup — run in foreground:
 
 ```
 Bash({ command: "maestro explore \"Where is X defined?\"" })

package/workflows/finish-work.md

@@ -8,7 +8,7 @@ Caller passes: `SESSION_DIR`, `SESSION_TYPE` (grill | brainstorm | analyze | blu
 
 ### 1. Detect outputs
 
-Scan `SESSION_DIR` for any of these files (any absent → skip silently):
+Scan `SESSION_DIR` for any of these files; if absent: log W0xx "<file> missing" and continue; flag harvest as [LOW CONFIDENCE] (partial fragments):
 
 | File | Source | Used for |
 |------|--------|----------|
@@ -46,7 +46,7 @@ Iterate detected files; build a `fragments[]` array. Each fragment: `{ kind, cat
 
 **Keyword extraction**: take 3-5 lowercased domain terms (filter stop words, take frequency-ranked nouns/identifiers from content).
 
-**Deduplication**: hash `(kind, content[:100])` — skip if any existing spec/knowhow entry has matching hash (check via `maestro spec list --json` + `maestro knowhow list --json`).
+**Deduplication**: hash `(kind, content[:100])` — skip if any existing spec/knowhow entry has matching hash (MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: check via `maestro spec list --json` + `maestro knowhow list --json`).
 
 ### 3. Route fragments
 
@@ -58,10 +58,10 @@ Apply? (auto | spec-only | knowhow-only | skip)
 
 Then for each fragment in approved buckets:
 
-- **spec**: `maestro spec add <category> "<title>" "<content>" --keywords {csv} --description "<one-line summary>" --source finish-work` (capture returned id into `extracted_spec_ids[]`)
-- **knowhow**: `maestro knowhow add --type {DCS|RCP|REF|KNW} --title "{title}" --body "{content}" --keywords {csv}` (capture id into `extracted_knowhow_ids[]`)
+- **spec**: MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: `maestro spec add <category> "<title>" "<content>" --keywords {csv} --description "<one-line summary>" --source finish-work` (capture returned id into `extracted_spec_ids[]`)
+- **knowhow**: MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: `maestro knowhow add --type {DCS|RCP|REF|KNW} --title "{title}" --body "{content}" --keywords {csv}` (capture id into `extracted_knowhow_ids[]`)
 - Below confidence threshold: increment `skipped_count`, do nothing
-- CLI failure: log W002, continue with remaining fragments
+- CLI failure: log W002, continue with remaining fragments; flag harvest as [LOW CONFIDENCE] (CLI failure)
 
 ### 3.5 Domain Term Extraction (interactive, conditional)
 
@@ -79,7 +79,7 @@ Process:
   2. 过滤已注册的 `glossary.yaml` terms
   3. 0 个新候选 → 跳过（静默）
   4. ≥ 1 个新候选 → 交互确认（domain 注册始终需要用户确认，`-y` 对 domain 无效）
-  5. 确认的术语写入 `glossary.yaml` via `maestro domain add`
+  5. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 确认的术语写入 `glossary.yaml` via `maestro domain add`
   6. 记录到 `archive.json` 的 `extraction.domain_ids[]`
 
 Skip conditions:

package/workflows/fork.md

@@ -42,7 +42,7 @@ milestoneSlug = kebab-case of milestoneName, max 40 chars.
 
 ## Step 4: Sync Mode (--sync)
 
-If `syncMode` is true, this is a sync operation on an existing worktree, not a fork.
+If `syncMode` is true, treat as sync operation on existing worktree, not a fork.
 
 ```
 IF syncMode:
@@ -154,7 +154,7 @@ Display:
   Or delegate (automated):
     maestro delegate "run full lifecycle for milestone" --cd {wtPath} --mode write
 
-  Sync worktree with main (if needed later):
+  Sync worktree with main (REQUIRED before merge):
     /maestro-fork -m {milestoneNum} --sync
 
   When all phases in milestone complete:

package/workflows/grill.md

@@ -82,8 +82,8 @@ output_dir = .workflow/scratch/{YYYYMMDD}-grill-{slug}/
 1. Read .workflow/project.md (if exists) → tech_stack, validated_requirements, active_requirements
 2. Read .workflow/state.json (if exists) → accumulated_context, artifacts[]
 3. Read .workflow/roadmap.md (if exists) → phase structure
-4. specs_content = maestro spec load --category arch
-5. wiki_hits = maestro wiki search "{topic keywords}"
+4. specs_content = maestro spec load --category arch  # MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
+5. wiki_hits = maestro wiki search "{topic keywords}"  # MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 ```
 
 ### 2.2: Load Upstream Material
@@ -97,7 +97,7 @@ Store as `upstream_material` (in-memory).
 
 ### 2.3: Codebase Scan
 
-Spawn `Agent(subagent_type: Explore)` to map the codebase surface relevant to the topic:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: spawn `Agent(subagent_type: Explore)` to map the codebase surface relevant to the topic:
 
 ```
 Agent(
@@ -116,7 +116,7 @@ Agent(
 )
 ```
 
-Store as `codebase_context`. W001 on failure: continue without code grounding.
+Store as `codebase_context`. W001 on failure: continue without code grounding; flag grill output as [LOW CONFIDENCE] (no code grounding).
 
 ### 2.4: Initialize Report
 
@@ -191,7 +191,7 @@ AskUserQuestion({
 })
 ```
 
-**Auto mode (`-y`)**: Use CLI exploration to resolve — prefer existing code naming unless semantically wrong.
+**Auto mode (`-y`)**: Use CLI exploration to resolve — prefer existing code naming; override only when name is semantically incorrect (verify via symbol lookup).
 
 ### 3.4: Write Terminology File
 
@@ -302,6 +302,7 @@ AskUserQuestion({
 
 **Auto mode**: Instead of asking the user, use code exploration to answer:
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 maestro delegate "PURPOSE: Answer '{question}' for the proposal '{topic}'
 TASK: Search codebase for evidence | Analyze existing patterns | Determine most likely answer
 MODE: analysis

package/workflows/harvest.md

@@ -217,11 +217,11 @@ Fragments extracted: 8 (filtered from 12 by confidence ≥ 0.5)
 
 ### 6a. Wiki routing
 
-`maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id>`. Fallback: write `.workflow/harvest/wiki-pending-{id}.md`.
+`maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id>`. Fallback: write `.workflow/harvest/wiki-pending-{id}.md`; flag wiki entry as [LOW CONFIDENCE] (pending offline).
 
 ### 6b. Spec routing
 
-`Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Mapping: pattern→pattern, decision→decision, bug→bug, knowhow→rule.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: `Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Mapping: pattern→pattern, decision→decision, bug→bug, knowhow→rule.
 
 ### 6c. Issue routing
 

package/workflows/impeccable.md

@@ -70,7 +70,7 @@ Keep concise: 5-15 bullet points maximum. Capture decisions, not process.
 
 ### For DCS- (decision), TIP- (tip), REF- (reference)
 
-Use `store_knowhow` MCP tool:
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: use `store_knowhow` MCP tool:
 
 ```json
 {
@@ -146,6 +146,7 @@ Create both:
 For decision and asset entries, create a spec reference for discoverability:
 
 ```bash
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 maestro spec add ui "<title>" "<one-line summary>" \
   --keywords impeccable,<command>,<domain keywords> \
   --ref "knowhow/<filename>"
@@ -164,4 +165,4 @@ Output one-line harvest summary:
 查看: maestro wiki load <id>
 ```
 
-If harvest fails, emit W001 and continue (command execution already succeeded).
+If harvest fails, emit W001 and continue (command execution already succeeded); flag harvest as [LOW CONFIDENCE] (harvest failed).