maestro-flow 0.5.34 → 0.5.36

package/workflows/agy-instructions.md

@@ -1,7 +1,5 @@
 # Maestro for Antigravity CLI
 
-Workflow orchestration CLI with MCP endpoint support and extensible architecture, adapted for Antigravity CLI tooling.
-
 - **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
 
 ## Delegate & CLI
@@ -11,8 +9,6 @@ Workflow orchestration CLI with MCP endpoint support and extensible architecture
 
 **Strictly follow the cli-tools.json configuration**
 
-Available CLI endpoints are dynamically defined by the config file. Use `maestro delegate --to agy` to dispatch tasks to the Antigravity CLI.
-
 ## Antigravity Tool Priority
 
 When choosing between equivalent tools, prefer the agy native primitives over shell fallbacks:

package/workflows/analyze.md

@@ -163,11 +163,13 @@ Parse $ARGUMENTS to determine mode and flags:
    - `constraints[status=open]` → prioritize for analysis
    - `open_questions[]` → seed discussion topics
 6. Load project specs: `specs_content = maestro spec load --category arch`
+7. Load domain glossary: read `.workflow/domain/glossary.yaml`（如存在）— 分析过程中使用 canonical term names 保持术语一致性；新发现的术语候选记入 `context-package.json#domain.terminology[]`
 
 **Load prior context** (adhoc/standalone scope):
 1. Read `.workflow/project.md` (if exists) — project vision, Validated requirements, Active requirements, Key Decisions
 2. Read `.workflow/state.json` (if exists) → `accumulated_context` (key_decisions, deferred, blockers)
 3. Load project specs: `specs_content = maestro spec load --category arch`
+4. Load domain glossary: read `.workflow/domain/glossary.yaml`（如存在）
 
 **Quick mode routing**: If QUICK_MODE, skip to Step 8 (Decision Extraction) after loading context.
 
@@ -525,8 +527,6 @@ Implementer's choice. Research suggests: {relevant finding from researchContext}
 (e.g., "Standard Stack recommends React Query for server state. Common pitfall: avoid mixing with Redux for async.")
 ```
 
-This makes research findings visible to the planner through context.md without imposing hard constraints.
-
 **8.5: Write context.md**
 
 Write to `OUTPUT_DIR/context.md`:

package/workflows/boundary-grill.md

@@ -0,0 +1,50 @@
+# Boundary Grill — Embedded Mini-Review Protocol
+
+
+## Conflict Types
+
+| ID | Signal | Example |
+|----|--------|---------|
+| `RSC` | Decision outside command's scope guard | analyze outputs task-level details (plan scope) |
+| `MOD` | Changes cross 2+ module boundaries | task touches `commands/` and `hooks/` without declaring cross-module |
+| `DEC` | Upstream locked decision contradicts code | locked "use EventEmitter" but code uses Subject at `file:line` |
+
+## Trigger
+
+Run boundary grill when ANY of:
+- **RSC**: produced decision matches another command's scope guard keywords
+- **MOD**: `ARCHITECTURE.md` exists AND changes touch 2+ top-level modules
+- **DEC**: upstream Locked decisions AND code grep shows contradicting patterns
+
+Priority when >3 conflicts: DEC > RSC > MOD.
+
+## Protocol
+
+Per conflict (max 3 conflicts × 3 questions = 9 total):
+1. State the conflict with `file:line` evidence
+2. Ask 2-3 adversarial questions via AskUserQuestion — challenge with code reality
+3. Resolve: RESOLVED (evidence-based) / DEFERRED (needs escalation) / ACCEPTED_RISK
+
+**Auto mode (`-y`)**: skip questions, resolve via code evidence weighting:
+- RSC → defer to target scope
+- MOD → follow existing cross-module pattern (or flag as risk)
+- DEC → code wins (current code = ground truth)
+
+## Output
+
+Append to calling command's primary output:
+
+```markdown
+## Boundary Grill Results
+
+| # | Type | Conflict | Resolution | Evidence |
+|---|------|----------|------------|----------|
+```
+
+Feed into `context.md`: resolved DEC → amend Locked; unresolved → Deferred with `boundary_grill: true`.
+
+## Constraints
+
+- Non-blocking — warnings + resolutions, never hard stops
+- Evidence MUST include `file:line` — generic assertions invalid
+- Results visible in command output — no silent swallowing

package/workflows/brainstorm.md

@@ -1,7 +1,5 @@
 # Workflow: Brainstorm
 
-Dual-mode brainstorming: auto pipeline (full multi-role analysis) or single role analysis.
-
 ## Architecture
 
 ```
@@ -202,9 +200,12 @@ Pass into Steps 2 and 3.
 
 ### Step 2: Terminology & Boundary Definition (Auto Mode)
 
-1. Extract 5-10 core domain terms (merge upstream locked terms if available)
-2. AskUserQuestion for Non-Goals (multiSelect, include "其他" option)
-3. Store terminology + non_goals to session
+1. Load existing domain terms: read `.workflow/domain/glossary.yaml` 中已注册术语，避免重复定义
+2. Extract 5-10 core domain terms (merge upstream locked terms + existing glossary terms)
+3. AskUserQuestion for Non-Goals (multiSelect, include "其他" option)
+4. Store terminology + non_goals to session
+
+新候选术语仅存入 `context-package.json#domain.terminology[]`，不直接写 glossary.yaml。由 chain 末尾 `manage-harvest --auto` 触发 finish-work Step 3.5 统一提升为正式术语。
 
 **Skip if**: `--yes` (auto-generate terms, empty non-goals)
 

package/workflows/claude-instructions.md

@@ -5,18 +5,45 @@
 ## Delegate & CLI
 
 - **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **Explore Usage**: @~/.maestro/workflows/explore-usage.md
 - **CLI Endpoints Config**: @~/.maestro/cli-tools.json
 
 **Strictly follow the cli-tools.json configuration**
 
+## Explore Priority
+
+Commands with codebase exploration/search steps should prefer `maestro explore` over inline Grep/Read:
+- **odyssey-\*** (archaeology, explore, discover phases)
+- **analyze, blueprint, grill** (discovery/scan phases)
+- **learn-investigate** (evidence gathering)
+- **issue-discover** (multi-perspective scan)
+- **impeccable teach/explore** (codebase scan)
+
+Use structured prompt format (`FIND/SCOPE/EXCLUDE/ATTENTION/EXPECTED`) for targeted searches. Multi-prompt parallel for multi-angle scans.
+
 ## Knowledge System
 
-**Gate rule: On any coding/modification/debugging task, the FIRST tool call MUST be `maestro search`. Do NOT read code or edit files until search is done.**
+**Gate rule: On any coding/modification/debugging task, run `maestro search` BEFORE reading code or editing files. Use targeted queries — multiple short searches beat one long one.**
 
 ### Required search (every task, no exceptions)
 
 ```bash
-maestro search "<feature/module keywords>"
+maestro search "<1-3 word topic phrase>"
+```
+
+**Query rules:**
+- Use **1-3 core keywords** per query — never dump all context into one search
+- Separate concepts from symbols: `maestro search "topology layout"` then `maestro search "DetailedTopologySVG" --code`
+- Run multiple targeted searches rather than one broad query
+
+```bash
+# ❌ Bad: keyword dump (5+ unrelated terms → diluted BM25 scores)
+maestro search "topology display frontend DetailedTopologySVG elk"
+
+# ✅ Good: targeted multi-search
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro search "elk layout" --type knowhow
 ```
 
 Then add follow-up searches based on results:

package/workflows/codebase-rebuild.md

@@ -204,7 +204,6 @@ Uses the native `maestro kg index` command (`src/graph/analyzers/fs-analyzer.ts`
 maestro kg index --src "$PROJECT_ROOT/src"
 ```
 
-This single command performs:
   - File system scan and code entity extraction (nodes, edges)
   - Import/call graph analysis and test pairing (tested_by edges)
   - Layer classification and topological tour generation

package/workflows/codex-instructions.md

@@ -1,34 +1,117 @@
 # Codex Code Guidelines
-## Delegate & CLI
+
 
 - **Delegate Usage**: @~/.maestro/workflows/delegate-usage.md
+- **Explore Usage**: @~/.maestro/workflows/explore-usage.md
 - **CLI Endpoints Config**: @~/.maestro/cli-tools.json
 
 **Strictly follow the cli-tools.json configuration**
 
-## Core Principles
+## Explore Priority
+
+Commands with codebase exploration/search steps should prefer `maestro explore` over inline Grep/Read:
+- **odyssey-\*** (archaeology, explore, discover phases)
+- **analyze, blueprint, grill** (discovery/scan phases)
+- **learn-investigate** (evidence gathering)
+- **issue-discover** (multi-perspective scan)
+- **impeccable teach/explore** (codebase scan)
+
+Use structured prompt format (`FIND/SCOPE/EXCLUDE/ATTENTION/EXPECTED`) for targeted searches. Multi-prompt parallel for multi-angle scans.
+
+# Coding Philosophy
+
+## Core Beliefs
+
+- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
+- **Embrace extreme simplicity** - Complexity is the root of all evil
+- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
+- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
+- **Never break backward compatibility** - Existing functionality is sacred and inviolable
+- **Incremental progress over big bangs** - Small changes that compile and pass tests
+- **Learning from existing code** - Study and plan before implementing
+- **Clear intent over clever code** - Be boring and obvious
+- **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
+- **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
+
+## Simplicity Means
+
+- Single responsibility per function/class
+- Avoid premature abstractions
+- No clever tricks - choose the boring solution
+- If you need to explain it, it's too complex
+
+## Fix, Don't Hide
+
+**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
+
+**NEVER**:
+- Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
+- Use suppression mechanisms (`skip`, `ignore`, `disable`) without fixing root cause
 
-- Follow project's existing patterns and conventions
-- Single responsibility, DRY, YAGNI
-- Small testable changes, commit frequently
-- Study 3+ similar patterns before implementing
-- Boring solutions over clever code
+**ALWAYS**:
+- Plan complex tasks thoroughly before implementation
+- Generate task decomposition for multi-module work (>3 modules or >5 subtasks)
+- Track progress using TODO checklists for complex tasks
+- Validate planning documents before starting development
+- Commit working code incrementally
+- Update plan documentation and progress tracking as you go
+- Learn from existing implementations
+- Stop after 3 failed attempts and reassess
+- **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
 
-**Git Operations:**
-- Only stage/commit files produced by current task
-- Use `git add <specific-files>` instead of `git add .`
+## Learning the Codebase
 
-**Multi-CLI Coexistence (CRITICAL):**
-- Conflicts with uncommitted changes → **STOP and report**, never overwrite
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+## Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Content Uniqueness Rules
+
+- **Each layer owns its abstraction level** - no content sharing between layers
+- **Reference, don't duplicate** - point to other layers, never copy content
+- **Maintain perspective** - each layer sees the system at its appropriate scale
+- **Avoid implementation creep** - higher layers stay architectural
+
+# Context Requirements
+
+Before implementation, always:
+- Identify 3+ existing similar patterns
+- Map dependencies and integration points
+- Understand testing framework and coding conventions
 
 ## Knowledge System
 
-**Gate rule: On any coding/modification/debugging task, the FIRST tool call MUST be `maestro search`. Do NOT read code or edit files until search is done.**
+**Gate rule: On any coding/modification/debugging task, run `maestro search` BEFORE reading code or editing files. Use targeted queries — multiple short searches beat one long one.**
 
 ### Required search (every task, no exceptions)
 
 ```bash
-maestro search "<feature/module keywords>"
+maestro search "<1-3 word topic phrase>"
+```
+
+**Query rules:**
+- Use **1-3 core keywords** per query — never dump all context into one search
+- Separate concepts from symbols: `maestro search "topology layout"` then `maestro search "DetailedTopologySVG" --code`
+- Run multiple targeted searches rather than one broad query
+
+```bash
+# ❌ Bad: keyword dump (5+ unrelated terms → diluted BM25 scores)
+maestro search "topology display frontend DetailedTopologySVG elk"
+
+# ✅ Good: targeted multi-search
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro search "elk layout" --type knowhow
 ```
 
 Then add follow-up searches based on results:

package/workflows/command-authoring.md

@@ -526,7 +526,7 @@ The two styles are complementary: FSM orchestrators invoke pipeline commands; pi
 | Style | Commands |
 |-------|----------|
 | **Pipeline** | init, analyze, plan, execute, verify, brainstorm, grill, blueprint, roadmap, milestone-audit, milestone-complete, milestone-release |
-| **FSM** | ralph, ralph-execute, ralph-beta |
+| **FSM** | ralph, ralph-execute |
 | **Needs evaluation** | coordinate (multi-role handoff may need FSM) |
 
 ---

package/workflows/debug.md

@@ -1,9 +1,5 @@
 # Debug Workflow
 
-Scientific method debugging with subagent isolation. Three modes: **Standalone** (user describes issue), **From UAT** (`--from-uat`, pre-filled symptoms), **Parallel** (`--parallel`, concurrent agents per gap cluster).
-
-Output: `understanding.md` + `evidence.ndjson` per investigation.
-
 ---
 
 ## Iron Law

package/workflows/domain-add.md

@@ -0,0 +1,115 @@
+---
+name: domain-add
+alias: domain-add
+---
+
+# Workflow: domain-add
+
+Register a domain term into `.workflow/domain/glossary.yaml`.
+
+## Arguments
+
+```
+$ARGUMENTS: "<canonical> <definition>"
+
+canonical -- kebab-case term name (e.g. "auth-token", "event-bus")
+definition -- one-line definition (≤200 chars)
+```
+
+## Prerequisites
+
+- `.workflow/domain/` directory must exist (run `maestro domain init` if missing)
+
+## Execution Steps
+
+### Step 1: Parse Arguments
+
+```
+Parse $ARGUMENTS:
+  1. canonical = first token (kebab-case, e.g. "auth-token")
+  2. definition = remaining text
+Validate:
+  - canonical is non-empty, kebab-case (lowercase, hyphens only)
+  - definition is non-empty, ≤200 chars
+On failure: show usage `domain-add <canonical> "<definition>"`, exit
+```
+
+### Step 2: Check Glossary State
+
+Verify `.workflow/domain/glossary.yaml` exists. If not, create via `maestro domain init`.
+
+Read existing glossary and check for:
+- **Exact duplicate**: same canonical name already registered → report existing entry, exit
+- **Near match**: Levenshtein distance ≤ 2 or alias overlap → warn, ask to confirm or merge
+
+### Step 3: Extract Metadata
+
+Auto-derive from the definition and codebase context:
+
+- **aliases** (1-3): common abbreviations, Chinese translations, or alternate forms the term is known by
+- **keywords** (3-5): search terms for discovery
+- **tier**: `core` (fundamental project concept) | `extended` (secondary) | `peripheral` (rarely referenced)
+- **relationships**: scan existing glossary for related terms (semantic overlap or dependency)
+
+### Step 4: Register Term
+
+Write via `maestro domain add`:
+
+```bash
+maestro domain add "<canonical>" "<definition>" --tier <tier>
+```
+
+If aliases or relationships identified, update immediately:
+
+```bash
+maestro domain update "<canonical>" --aliases "alias1,alias2" --keywords "kw1,kw2,kw3" --relationships "related-term-1,related-term-2"
+```
+
+Records `source.kind = 'manual'`, `source.registered_at = now`.
+
+### Step 5: Verify Injection
+
+Confirm the term is injectable by checking:
+
+```bash
+maestro domain show "<canonical>"
+```
+
+Display: canonical name, definition, aliases, tier, relationships, and verify command:
+```
+maestro domain list
+```
+
+### Step 6: Report
+
+```
+=== DOMAIN TERM REGISTERED ===
+Term:      {canonical}
+Definition: {definition}
+Aliases:   {alias1, alias2}
+Tier:      {tier}
+Related:   {rel1, rel2}
+Injection: domain-compact (always) + domain-expanded (on keyword match)
+Next:      maestro domain list | maestro domain discover (find more candidates)
+```
+
+## Auto-Discovery Alternative
+
+For batch registration from codebase scanning:
+
+```bash
+maestro domain discover    # scan codebase for term candidates
+maestro domain import      # batch import from external source
+```
+
+## Domain Term Lifecycle
+
+```
+discover/manual → register → active → (optional) deprecated → removed
+                                ↑
+                          update aliases/keywords/relationships
+```
+
+## Output
+
+One domain term entry added to `.workflow/domain/glossary.yaml`.

package/workflows/execute.md

@@ -589,6 +589,13 @@ Append unique entries to .workflow/specs/learnings.md using <spec-entry> closed-
   category="learning", keywords (3-5 terms), date, source="execute"
 
 Mark artifact.harvested = true; write state.json (atomic)
+
+// Domain knowledge note:
+// E5 仅提取 incremental learnings (spec category=learning)。
+// 完整的知识提取（constraints → spec, decisions → knowhow, terminology → domain glossary）
+// 由 chain 末尾的 manage-harvest --auto 触发 finish-work 统一处理。
+// Domain compact/expanded 注入是 hook 自动行为，execute 期间无需手动加载——
+// 已注册术语通过 keyword-spec-injector 自动注入到 agent context 中。
 ```
 
 ---

package/workflows/explore-usage.md

@@ -0,0 +1,128 @@
+# Explore Usage
+
+```bash
+maestro explore "<PROMPT>" [more prompts...] [options]
+```
+
+## When to Use
+
+| Scenario | Example |
+|----------|---------|
+| Multi-angle codebase scan | 3 prompts scanning DB/API/error patterns in parallel |
+| Quick code lookup | Single prompt, foreground |
+| Per-prompt endpoint routing | JSON file with different endpoints per prompt |
+| Lightweight read-only analysis | Where delegate is overkill (no session, no history) |
+
+**Not for**: write-mode tasks, long sessions, interactive follow-ups — use `delegate` instead.
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-e, --endpoint <names>` | Endpoint name(s), comma-separated | First available |
+| `--all` | Fan out each prompt to all endpoints | — |
+| `--parallel <n>` | Max concurrent endpoint queues | Config or `4` |
+| `--ep-concurrency <n>` | Max concurrent jobs per endpoint | `1` (serial) |
+| `--max-turns <n>` | Max agent turns per job | Config or `6` |
+| `-f, --file <path>` | Load prompts from JSON or text file | — |
+| `--cd <dir>` | Working directory | Current |
+| `-o, --output-dir <dir>` | Custom session save directory | `.workflow/explore/` |
+| `--no-save` | Skip session save | — |
+| `--json` | Output results as JSON | — |
+
+**1 prompt = 1 agent**. Endpoint resolution: `--endpoint` > `--all` > first available.
+
+## Prompt Template
+
+```
+FIND: [what to search for — the core query]
+SCOPE: [file patterns, directories, or modules]
+EXCLUDE: [what to skip — files, patterns, false positives]
+ATTENTION: [caveats, edge cases, things to watch for]
+EXPECTED: [output format — evidence list, summary, JSON]
+```
+
+Only `FIND` required. Plain text (no `FIND:` prefix) also works.
+
+| Field | Role | Example |
+|-------|------|---------|
+| `FIND` | What to search for | `All database query patterns that could cause N+1` |
+| `SCOPE` | Where to look | `src/db/**/*.ts`, `src/api/` |
+| `EXCLUDE` | What to skip | `test files, generated code, node_modules` |
+| `ATTENTION` | What to watch for | `ORM lazy-loading traps, raw SQL in service layer` |
+| `EXPECTED` | Output format | `file:line evidence list with severity` |
+
+## Execution Model
+
+**Serial within endpoint, parallel across endpoints.**
+
+Same API → jobs queue and run one-by-one (avoids rate limits).
+Different APIs → queues run concurrently.
+
+```
+Endpoint A:  [job1] → [job2] → [job3]    (serial)
+Endpoint B:  [job4] → [job5]              (serial)
+                                           ↑ parallel ↑
+```
+
+Raise per-endpoint parallelism with `--ep-concurrency 2` when the API allows it.
+
+## Multi-Prompt Input
+
+**Inline**: `maestro explore "prompt1" "prompt2" "prompt3"`
+
+**JSON file** (`-f prompts.json`):
+
+```json
+[
+  "simple string prompt",
+  { "prompt": "FIND: auth bypass\nSCOPE: src/api/", "endpoint": "deepseek" }
+]
+```
+
+Per-prompt `endpoint` overrides global `--endpoint`.
+
+**Text file** (`-f prompts.txt`): paragraphs separated by blank lines.
+
+**Mixed**: `maestro explore "inline" -f file.json`
+
+## Session
+
+Results auto-save to `.workflow/explore/{session-id}.json` per workspace.
+
+```bash
+maestro explore show                  # list sessions
+maestro explore output <id>           # view session results
+maestro explore output <id> --json    # JSON output
+```
+
+## Endpoint Config
+
+File: `~/.maestro/api-explore.json`
+
+```json
+{
+  "endpoints": {
+    "qwen": { "baseUrl": "https://...", "apiKey": "sk-xxx", "model": "Qwen/Qwen3-8B" },
+    "deepseek": { "baseUrl": "https://...", "apiKey": "sk-yyy", "model": "deepseek-chat" }
+  },
+  "maxTurns": 6,
+  "concurrency": 4
+}
+```
+
+Proxy auto-inherited from `~/.maestro/cli-tools.json`. Legacy single-endpoint and env vars also supported.
+
+## Execution Rules
+
+Multi-prompt — **background**:
+
+```
+Bash({ command: "maestro explore \"p1\" \"p2\" --json", run_in_background: true })
+```
+
+Single quick lookup — foreground is fine:
+
+```
+Bash({ command: "maestro explore \"Where is X defined?\"" })
+```

package/workflows/finish-work.md

@@ -1,7 +1,5 @@
 # Workflow: finish-work
 
-Last step of session commands. Inline-extracts spec/knowhow from this single session, then writes `archive.json` so the session enters `wiki search` (strategy 2: only sealed/archived sessions are indexed).
-
 ## Inputs
 
 Caller passes: `SESSION_DIR`, `SESSION_TYPE` (grill | brainstorm | analyze | blueprint | plan | execute | verify), `SESSION_ID`, `LINKED_MILESTONE` (optional).
@@ -78,10 +76,10 @@ Source priority:
 
 Process:
   1. 从 session 产物中收集术语候选
-  2. 过滤已注册的 `glossary.json` terms
+  2. 过滤已注册的 `glossary.yaml` terms
   3. 0 个新候选 → 跳过（静默）
   4. ≥ 1 个新候选 → 交互确认（domain 注册始终需要用户确认，`-y` 对 domain 无效）
-  5. 确认的术语写入 `glossary.json` via `maestro domain add`
+  5. 确认的术语写入 `glossary.yaml` via `maestro domain add`
   6. 记录到 `archive.json` 的 `extraction.domain_ids[]`
 
 Skip conditions:
@@ -130,8 +128,6 @@ Next: /maestro-milestone-complete will flip lifecycle.status → archived and pr
 
 ## Idempotency
 
-Re-running on same session: archive.json overwritten with fresh timestamps. Steps 2-3 skipped when existing `archive.json.extraction.harvested == true` (avoids duplicate spec/knowhow). Force re-extract: delete `archive.json` first.
-
 ## Boundary
 
 - Does NOT flip `archived_at` or move files — that is milestone-complete Step 2.3.

package/workflows/fork.md

@@ -1,9 +1,5 @@
 # Workflow: fork
 
-Create a git worktree for an entire milestone, enabling inter-milestone parallel development. Copies `.workflow/` context into the worktree since `.workflow/` is gitignored.
-
-Worktrees operate at the **milestone level** — all phases within a milestone are owned by one worktree and executed sequentially inside it. Per-phase parallelism within a milestone is not supported.
-
 ---
 
 ## Step 1: Parse Arguments and Flags

package/workflows/grill.md

@@ -451,7 +451,20 @@ Write `{output_dir}/context-package.json`:
 }
 ```
 
-### 7.2: Completion Report
+### 7.2: Domain Knowledge Flow
+
+Grill 产出的领域术语通过以下路径沉淀到项目知识库：
+
+```
+terminology.md (locked terms)  ──→  finish-work Step 3.5  ──→  .workflow/domain/glossary.yaml
+context-package.json#domain.terminology[]  ──→  finish-work Step 3.5  ──→  glossary.yaml
+```
+
+- Grill 期间**不应**直接调用 `maestro domain add` — 术语在 grilling 过程中可能被修改或推翻
+- 所有术语经 Step 5 synthesis 锁定后，由 chain 末尾的 `manage-harvest --auto` 自动触发 finish-work 提取
+- finish-work Step 3.5 的 domain extraction 始终交互确认（`-y` 对 domain 注册无效）
+
+### 7.3: Completion Report
 
 ```
 Grill session {artifact_id} completed.

package/workflows/harvest.md

@@ -1,6 +1,5 @@
 # Harvest Workflow
 
-Extract knowledge from **any workflow artifact** (analysis, brainstorm, debug, lite-plan/fix, scratchpad, sessions) and route into wiki / spec / issue stores.
 
 ---
 
@@ -260,8 +259,6 @@ For each routed item, record in `.workflow/harvest/harvest-log.jsonl`:
 }
 ```
 
-This log prevents duplicate harvesting in future runs.
-
 ---
 
 ## Stage 7: dedup_check

package/workflows/impeccable/audit.md

@@ -1,7 +1,5 @@
 Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.
 
-This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.
-
 ## Diagnostic Scan
 
 Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.