maestro-flow 0.5.2 → 0.5.31

package/workflows/execute.md

@@ -1,43 +1,16 @@
 # Execute Workflow
 
-Wave-based parallel execution with atomic commits, breakpoint resume, built-in verification gate, and optional sync/reflection.
-
-Core principle: **Execute per-plan, not per-phase.** Each plan's wave DAG runs independently. Multiple plans execute sequentially. Verification is an integral post-gate — not a separate command.
+Wave-based parallel execution with atomic commits, breakpoint resume, built-in verification gate, and optional sync/reflection. Execute per-plan, not per-phase.
 
 ---
 
 ## Iron Law
 
-**VERIFY EACH TASK OUTPUT BEFORE MARKING COMPLETE.**
-
-Every task completion requires:
-1. Run convergence criteria checks (not just code review)
-2. Confirm output matches task definition expectations
+NEVER mark a task "completed" without running convergence criteria checks. Every completion requires:
+1. Run convergence criteria checks
+2. Confirm output matches task definition
 3. Evidence of verification in the task summary
 
-No task may be marked "completed" based on agent self-report alone.
-
----
-
-## Red Flags — These Thoughts Mean STOP
-
-If you catch yourself thinking any of these, STOP and verify:
-
-- "The agent said it's done, so it must be done"
-- "I'll batch-verify all tasks at the end instead of per-task"
-- "This task is too simple to need verification"
-- "The warning isn't relevant, I'll ignore it"
-- "Let me mark it complete and fix the issue later"
-
-All of these mean: **run convergence criteria check NOW before marking the task complete**.
-
----
-
-## Prerequisites
-
-- Plan exists in scratch directory: `plan.json` + `.task/TASK-*.json`
-- OR: executionContext handoff received from `/workflow:plan`
-
 ---
 
 ## Plan Resolution
@@ -76,8 +49,6 @@ For each PLAN_DIR in PLAN_DIRS (sequential):
 
 ## E0.5: Execution Options Confirmation
 
-**Purpose:** Let user choose how tasks execute. Reads available tools from `delegate-config show --json` to build dynamic options. Supports both menu selection and natural language intent. Skipped when `-y` flag or executionContext already confirmed.
-
 ### Skip conditions
 
 - `-y` flag → use resolved defaults, skip prompt
@@ -172,8 +143,6 @@ Store: `executionMethod`, `domainRouting`, `codeReviewTool`, `verificationTool`
 
 ## E1: Load Plan (per PLAN_DIR)
 
-**Purpose:** Build or receive the execution queue for a single plan.
-
 ### From executionContext handoff (preferred, first plan only)
 
 ```
@@ -233,8 +202,6 @@ Pass specs_content to each executor agent in E2.
 
 ## E2: Wave Parallel Execution
 
-**Purpose:** Execute tasks wave by wave, parallel within each wave. Supports multi-backend dispatch — tasks route to Agent or CLI tools (via `maestro delegate`) based on executor resolution.
-
 ### Executor Resolution
 
 Resolution priority: per-task assignment > explicit method > auto domain routing.
@@ -360,8 +327,6 @@ Continue wave (other tasks unaffected)
 
 ## E2.5: Post-Wave Validation
 
-**Purpose:** Validate execution integrity after all waves complete, before sync and reflection. Catches missing summaries, status inconsistencies, and tech stack constraint violations early.
-
 ### Check 1: Summary Existence
 
 ```
@@ -388,8 +353,6 @@ If constraints exist:
 
 ### Check 4: CLI Supplementary Validation (optional)
 
-**Purpose:** Use external CLI tool for semantic validation that structural checks miss — dead code, unused exports, circular dependencies introduced by execution.
-
 ```
 IF no CLI tools enabled OR completed_tasks.length == 0: skip
 
@@ -421,8 +384,6 @@ If none critical: log "passed" and continue to E2.6
 
 ## E2.6: Code Review (Optional)
 
-**Purpose:** Run code review on execution output if selected in E0.5.
-
 ```
 If codeReviewTool == "Skip": continue to E3
 
@@ -439,8 +400,6 @@ Wait for completion, log findings summary
 
 ## E2.7: Verification Gate
 
-**Purpose:** External model verifies execution output actually achieves convergence criteria and structural integrity. Replaces the standalone `maestro-verify` — verification is now an integral post-gate within execution. The executing agent does NOT verify itself; a separate model performs the cross-check.
-
 **Skip if** `verificationTool == "Skip"` OR `--skip-verify` flag OR no completed tasks.
 
 ### Step 1: Collect Verification Inputs
@@ -561,8 +520,6 @@ IF verification ran (not skipped):
 
 ## E3: Auto Sync
 
-**Purpose:** Update codebase documentation after execution.
-
 ```
 If config.json.codebase.auto_sync_after_execute == true:
   Trigger /workflow:sync logic:
@@ -578,8 +535,6 @@ Else:
 
 ## E4: Reflection (Optional)
 
-**Purpose:** Record strategy observations for future iterations.
-
 ```
 If config.json.workflow.reflection == true:
   Review execution results:
@@ -619,8 +574,6 @@ If NOT SCRATCH_MODE: sync state.json (status, clear current_task_id)
 
 ## E5: Register Artifact & Extract Learnings (per PLAN_DIR)
 
-**Purpose:** Register execution completion and extract incremental learnings.
-
 ```
 // Register EXC artifact
 Find matching plan artifact in state.json; create EXC artifact:
@@ -656,8 +609,6 @@ Mark artifact.harvested = true; write state.json (atomic)
 
 ## Breakpoint Resume
 
-The execute workflow is fully resumable:
-
 ```
 State tracked in index.json.execution:
   tasks_completed, current_wave, commits, method, default_executor,

package/workflows/finish-work.md

@@ -65,6 +65,30 @@ Then for each fragment in approved buckets:
 - Below confidence threshold: increment `skipped_count`, do nothing
 - CLI failure: log W002, continue with remaining fragments
 
+### 3.5 Domain Term Extraction (interactive, conditional)
+
+Prerequisites:
+  - `.workflow/domain/` 目录存在（不存在则跳过整个步骤）
+  - Session 包含术语源文件
+
+Source priority:
+  1. `terminology.md` (grill session) — locked terms with code references
+  2. `context-package.json#domain.terminology[]` — brainstorm/grill/import 产出
+  3. `conclusions.json#recommendations` with domain-like keywords
+
+Process:
+  1. 从 session 产物中收集术语候选
+  2. 过滤已注册的 `glossary.json` terms
+  3. 0 个新候选 → 跳过（静默）
+  4. ≥ 1 个新候选 → 交互确认（domain 注册始终需要用户确认，`-y` 对 domain 无效）
+  5. 确认的术语写入 `glossary.json` via `maestro domain add`
+  6. 记录到 `archive.json` 的 `extraction.domain_ids[]`
+
+Skip conditions:
+  - `.workflow/domain/` 不存在
+  - Session 无术语源文件
+  - 所有候选术语已注册
+
 ### 4. Write `archive.json`
 
 Overwrites; idempotent. Schema `session-archive/1.0`:
@@ -82,6 +106,7 @@ Overwrites; idempotent. Schema `session-archive/1.0`:
     "harvested_at": "{ISO now}",
     "spec_ids": [/* from Step 3 */],
     "knowhow_ids": [/* from Step 3 */],
+    "domain_ids": [/* from Step 3.5 */],
     "skipped_count": 0
   },
   "pruned": null

package/workflows/grill.md

@@ -1,6 +1,6 @@
 # Workflow: Grill
 
-Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time, challenges vague terminology against existing code, probes edge cases with concrete scenarios, and produces a verified context package for downstream brainstorm/analyze/roadmap consumption.
+Socratic stress-testing of a plan/idea/requirement against codebase reality. Produces a verified context package for downstream consumption.
 
 ## Architecture
 
@@ -76,8 +76,6 @@ output_dir = .workflow/scratch/{YYYYMMDD}-grill-{slug}/
 
 ## Step 2: Discovery
 
-Scan project documentation and codebase to build a grilling context. This grounds all subsequent questions in code reality.
-
 ### 2.1: Load Project State
 
 ```
@@ -118,9 +116,7 @@ Agent(
 )
 ```
 
-Store as `codebase_context`.
-
-If scan fails (W001): `codebase_context = null`, continue without code grounding.
+Store as `codebase_context`. W001 on failure: continue without code grounding.
 
 ### 2.4: Initialize Report
 
@@ -159,14 +155,9 @@ Write `{output_dir}/grill-report.md` with header:
 
 ## Step 3: Terminology Alignment
 
-Extract terminology from the proposal/topic and cross-reference with codebase naming.
-
 ### 3.1: Extract Candidate Terms
 
-From topic text + upstream material, identify 5-15 candidate domain terms:
-- Nouns that appear as entities, concepts, or roles
-- Verbs that describe key operations
-- Adjectives that qualify system properties
+From topic + upstream, identify 5-15 domain terms (entity nouns, operation verbs, property adjectives).
 
 ### 3.2: Code Name Collision Check
 
@@ -218,12 +209,10 @@ Write `{output_dir}/terminology.md`:
 
 ## Step 4: Branch Walking (Core Grilling Loop)
 
-The heart of the grill. Walk the decision tree one branch at a time, one question per turn. Each branch is fully explored before moving to the next.
+One branch at a time, one question per turn. Each branch fully explored before next.
 
 ### Branch Categories
 
-Select branches based on `--depth`:
-
 | Priority | Branch | Shallow | Standard | Deep |
 |----------|--------|---------|----------|------|
 | 1 | Scope & Boundaries | ✓ | ✓ | ✓ |
@@ -237,11 +226,7 @@ Select branches based on `--depth`:
 
 ### Branch Walking Protocol
 
-For EACH selected branch:
-
 **4.1: Open the Branch**
-
-Append to `grill-report.md`:
 ```markdown
 ## Branch {N}: {branch_name}
 
@@ -252,13 +237,9 @@ Append to `grill-report.md`:
 
 **4.2: Generate Probing Questions**
 
-Based on the topic + codebase_context + terminology + prior branch decisions, generate 3-5 probing questions for this branch. Questions MUST:
-- Reference specific code findings from Step 2.3 when available
-- Use concrete scenarios, not abstract hypotheticals
-- Challenge assumptions ("You said X, but the code shows Y — how do you reconcile?")
-- Escalate from basic to adversarial
+Generate 3-5 probing questions per branch. MUST: reference code findings, use concrete scenarios, challenge assumptions, escalate from basic to adversarial.
 
-Question generation pattern per branch:
+Question patterns per branch:
 
 **Scope & Boundaries**:
 - "What is the smallest version of this that delivers value?"
@@ -331,15 +312,10 @@ CONSTRAINTS: Answer based on code evidence only, flag uncertainty" --role analyz
 
 **4.4: Validate Answer Against Code**
 
-After each answer, verify against codebase when possible:
-- If user says "We'll use X pattern" → Grep for existing X usage, confirm consistency
-- If user says "This won't affect Y" → Explore call chains to verify isolation
-- If contradiction found → immediately challenge:
-
-```
-"You said {answer}, but I found {code_evidence} at {file:line}. 
-This suggests {contradiction}. How do you reconcile?"
-```
+After each answer, verify against codebase:
+- "We'll use X pattern" → Grep for existing X usage, confirm consistency
+- "This won't affect Y" → Explore call chains to verify isolation
+- Contradiction found → immediately challenge with code evidence
 
 **4.5: Record Decision**
 
@@ -354,24 +330,17 @@ After each question is settled, immediately append to `grill-report.md`:
 **Constraint**: {if locked, the RFC 2119 statement — e.g., "MUST use event sourcing for audit trail"}
 ```
 
-Update the branch header: increment questions/decisions counts.
-
 **4.6: Branch Completion**
 
-When all questions in a branch are asked (or user signals "enough"):
-- Update branch status to ✅ Completed
-- Update Branch Log table in report header
-- Move to next branch
+All questions asked (or user signals "enough") → update branch status, update Branch Log table, move to next.
 
 ---
 
 ## Step 5: Synthesis
 
-After all branches are walked (or max rounds reached):
-
 ### 5.1: Decision Summary
 
-Read all branch decisions from `grill-report.md`. Classify:
+Classify all branch decisions:
 
 | Classification | Criteria | Downstream Use |
 |----------------|----------|----------------|
@@ -381,8 +350,6 @@ Read all branch decisions from `grill-report.md`. Classify:
 
 ### 5.2: Risk Register
 
-Extract unresolved tensions, contradictions found during grilling, and branches not fully explored:
-
 ```markdown
 ## Risk Register
 
@@ -500,14 +467,3 @@ Next steps:
   /maestro-roadmap --from grill:{artifact_id}                — Direct to roadmap (if scope is clear)
 ```
 
----
-
-## Quality Criteria
-
-- grill-report.md has at least `{depth_branch_count}` completed branches
-- Each branch has ≥ 2 question-answer pairs with evidence
-- terminology.md has ≥ 5 terms with code references where applicable
-- context-package.json passes schema validation (all required fields present)
-- No locked decision lacks evidence (code reference or explicit user confirmation)
-- Risk register captures all unresolved contradictions found during grilling
-- Branch Log table in report header is fully populated with final status

package/workflows/harvest.md

@@ -1,16 +1,6 @@
 # Harvest Workflow
 
-Extract knowledge from workflow artifacts and route into wiki / spec / issue stores.
-
-Unlike `retrospective.md` which is phase-scoped and post-execution, harvest operates on **any workflow session artifact** — analysis results, brainstorm outputs, debug sessions, lite-plan/fix results, scratchpad notes, and completed workflow sessions.
-
----
-
-## Prerequisites
-
-- `.workflow/` initialized (`.workflow/state.json` exists)
-- At least one artifact source present (analysis, brainstorm, import, debug, lite-plan, lite-fix, scratchpad, or active session)
-- For wiki routing: `maestro wiki` CLI available
+Extract knowledge from **any workflow artifact** (analysis, brainstorm, debug, lite-plan/fix, scratchpad, sessions) and route into wiki / spec / issue stores.
 
 ---
 
@@ -40,8 +30,8 @@ Unlike `retrospective.md` which is phase-scoped and post-execution, harvest oper
 | `--dry-run` | Preview extracted items without writing to any store |
 | `-y` / `--yes` | Skip confirmation prompts, accept all routing |
 | `--min-confidence N` | Minimum extraction confidence 0.0-1.0 (default: 0.5) |
-| `--prune` | State hygiene mode: classify artifacts, graduate harvested ones to knowhow, archive from state.json, prune accumulated_context. **Note:** `harvest --prune` *promotes* artifacts to knowhow (and trims state.json); this differs from `knowhow.md`'s `prune` operation which *deletes* knowhow entries. The two `--prune` flags share a name but operate on different stores in opposite directions. |
-| `--age N` | Graduation age threshold in days (default: 14). Only artifacts older than N days are prune candidates. Used with `--prune` |
+| `--prune` | State hygiene: graduate harvested artifacts to knowhow, archive from state.json, prune accumulated_context |
+| `--age N` | Graduation age threshold in days (default: 14). Used with `--prune` |
 
 ---
 
@@ -60,8 +50,6 @@ If --prune: mode = "prune", jump to Stage 9 (skip Stages 2-8).
 
 ## Stage 2: discover_artifacts
 
-Scan `.workflow/` for harvestable artifacts. Each source type has a known structure:
-
 ### Source Registry
 
 | Source Type | Scan Path | Key Files | ID Pattern |
@@ -76,7 +64,7 @@ Scan `.workflow/` for harvestable artifacts. Each source type has a known struct
 | `import` | `.workflow/scratch/*-import-*/` | `context-package.json`, `source.*` | directory name |
 | `knowhow` | `.workflow/knowhow/` | `*.md`, `digest-*.md` | filename |
 
-Scan each source type (filtered by `--source`). For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title` (from JSON or H1), `updated_at`, `summary`, `file_count`.
+For each matching directory/file within `--recent` window, extract: `source_type`, `id`, `path`, `title`, `updated_at`, `summary`, `file_count`.
 
 ### Display candidates
 
@@ -106,25 +94,13 @@ Scan each source type (filtered by `--source`). For each matching directory/file
 
 ## Stage 3: load_and_extract (per selected artifact)
 
-For each selected artifact, load all files and extract knowledge fragments.
-
 ### 3a. Load artifact content
 
-Read all relevant files in the artifact directory. Build a content bundle:
-
-```
-bundle = {
-  source_type: "analysis" | "brainstorm" | ...,
-  id: session_id,
-  path: artifact_directory,
-  files: [{ name, content, type: "json"|"md" }],
-  metadata: extracted from key files (conclusions.json, plan.json, etc.)
-}
-```
+Build content bundle: `{ source_type, id, path, files[], metadata }`.
 
 ### 3b. Extract knowledge fragments
 
-Parse content to identify discrete knowledge items. Each source type has specific extraction patterns:
+Per source type:
 
 **Analysis (`conclusions.json` + markdown):**
 - `findings[]` → each finding is a fragment
@@ -179,23 +155,9 @@ Parse content to identify discrete knowledge items. Each source type has specifi
 **Learning Insights (`specs/learnings.md`):**
 - Each `<spec-entry>` → learning fragment (check if already routed to wiki/spec/issue)
 
-Each fragment gets:
-```
-fragment = {
-  id: "HRV-{8 hex}" from hash(source_id + content_hash),
-  source_type: ...,
-  source_id: ...,
-  title: extracted or inferred,
-  content: raw text,
-  tags: extracted from context,
-  category: "finding" | "decision" | "pattern" | "bug" | "risk" | "task" | "knowhow" | "recommendation",
-  confidence: 0.0-1.0 (based on specificity and actionability)
-}
-```
-
-Filter by `--min-confidence`.
+Each fragment: `{ id: "HRV-{8 hex}", source_type, source_id, title, content, tags, category, confidence: 0.0-1.0 }`. Filter by `--min-confidence`.
 
-**Context Package shortcut**: If any artifact has a `context-package.json` (check `state.json.artifacts[].context_package`), harvest can use it as a pre-extracted summary — skip detailed file parsing and directly convert context-package fields to fragments. The per-item `ref` field provides traceability to original sources.
+**Shortcut**: If artifact has `context-package.json`, convert its fields directly to fragments (skip detailed parsing).
 
 ---
 
@@ -216,13 +178,9 @@ For each fragment, determine the best routing target (unless `--to` forces a spe
 | `knowhow` | wiki (knowhow) | Generalizable insights → wiki knowledge |
 | `recommendation` | wiki (note) or issue | Actionable recommendations → issue; informational → wiki |
 
-### Override with `--to`
+`--to wiki|spec|issue` forces all fragments to that target. `--to auto` uses classification rules.
 
-`--to wiki|spec|issue` forces all fragments to that target. `--to auto` (default) uses classification rules above.
-
-### Build routing plan
-
-Group fragments into three buckets: `wiki` (fragment, wiki_type, slug, title, tags, body), `spec` (fragment, spec_type, content), `issue` (fragment, title, severity, description).
+Group into three buckets: `wiki`, `spec`, `issue`.
 
 ---
 
@@ -258,19 +216,17 @@ Fragments extracted: 8 (filtered from 12 by confidence ≥ 0.5)
 
 ## Stage 6: route_outputs
 
-Execute the routing plan. Each target uses existing infrastructure:
-
 ### 6a. Wiki routing
 
-Create via `maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id> --title --tags --body`. Types: note/knowhow/spec. Fallback on failure: write `.workflow/harvest/wiki-pending-{id}.md` with frontmatter.
+`maestro wiki create --type <wiki_type> --slug harvest-<source_type>-<short_id>`. Fallback: write `.workflow/harvest/wiki-pending-{id}.md`.
 
 ### 6b. Spec routing
 
-Route via `Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Category mapping: pattern→pattern, decision→decision, bug→bug, knowhow→rule.
+`Skill({ skill: "spec-add", args: "<spec_type> <content>" })`. Mapping: pattern→pattern, decision→decision, bug→bug, knowhow→rule.
 
 ### 6c. Issue routing
 
-For each issue item, append to `.workflow/issues/issues.jsonl` using the canonical schema from `workflows/issue.md`:
+Append to `.workflow/issues/issues.jsonl`:
 
 ```json
 {
@@ -310,7 +266,7 @@ This log prevents duplicate harvesting in future runs.
 
 ## Stage 7: dedup_check
 
-Before writing any item in Stage 6, check for duplicates across `harvest-log.jsonl` (by fragment_id), wiki (by title search), `issues.jsonl` (by title/description), and `specs/learnings.md` (by content). Duplicates are skipped with `[SKIP-DUP]` marker and logged to harvest report.
+Before writing in Stage 6, check: `harvest-log.jsonl` (fragment_id), wiki (title), `issues.jsonl` (title/description), `specs/learnings.md` (content). Duplicates → `[SKIP-DUP]`, logged to report.
 
 ---
 
@@ -379,7 +335,7 @@ Next:
 
 ## Stage 9: state_hygiene (--prune)
 
-When `--prune` flag is present, skip Stages 2-8 and run state.json hygiene instead. Manages three concerns: **artifact graduation** (harvested → archived via knowhow), **accumulated_context pruning** (remove resolved/stale entries), and **integrity validation**.
+Skip Stages 2-8. Three concerns: artifact graduation, accumulated_context pruning, integrity validation.
 
 ### 9a. Load state
 
@@ -400,9 +356,7 @@ For each artifact in `artifacts[]`, assign a classification:
 | `stale` | harvested == false AND not active AND age > age_threshold | **Suggest** harvest first |
 | `protected` | type ∈ {plan, execute} AND linked downstream artifact is active | **Keep** regardless of age |
 
-Age = days since `completed_at` (or `created_at` if never completed).
-
-"Referenced by active plan": artifact X is protected if any plan artifact has `depends_on == X.id` or any execute artifact in same phase is active.
+Age = days since `completed_at` (or `created_at`). Protected if referenced by any active plan/execute artifact.
 
 ### 9c. Classify accumulated_context
 
@@ -519,9 +473,9 @@ Append prune results to harvest report:
 
 ### Safety invariants
 
-1. **Never prune current milestone artifacts** — active classification takes precedence
-2. **Never delete files on disk** — only state.json entries move; files remain for reference/audit
-3. **Backup before write** — always create `state.json.backup-prune-{timestamp}`
-4. **Stale before graduate** — stale artifacts are flagged, not silently archived (knowledge would be lost)
-5. **Spec dedup is conservative** — key_decision pruned only if verbatim match found in specs
-6. **Idempotent** — re-running `--prune` with no changes produces empty plan
+1. NEVER prune current milestone artifacts
+2. NEVER delete files on disk — only state.json entries move
+3. ALWAYS backup before write (`state.json.backup-prune-{timestamp}`)
+4. ALWAYS flag stale artifacts before graduating (prevent knowledge loss)
+5. Spec dedup: only prune key_decisions with verbatim match in specs
+6. Idempotent: re-running with no changes produces empty plan