maestro-flow 0.5.37 → 0.5.38

package/workflows/agy-instructions.md

@@ -1,122 +1,161 @@
-# Maestro for Antigravity CLI
+# Codex Code Guidelines
 
-- **Coding Philosophy**: @~/.maestro/workflows/coding-philosophy.md
-
-## 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**
 
-## Antigravity Tool Priority
-
-When choosing between equivalent tools, prefer the agy native primitives over shell fallbacks:
-
-| Need | Prefer | Fallback |
-|------|--------|----------|
-| Read a file | `view_file(AbsolutePath, StartLine, EndLine)` | `run_command("Get-Content ...")` |
-| Read external URL | `read_url_content(Url)` | `run_command("curl ...")` |
-| Create / overwrite file | `write_to_file(TargetFile, CodeContent, Overwrite)` | n/a |
-| Single-block edit | `replace_file_content(TargetFile, StartLine, EndLine, TargetContent, ReplacementContent)` | n/a |
-| Multi-block edit on same file | `multi_replace_file_content(TargetFile, ReplacementChunks=[...])` | repeated `replace_file_content` |
-| Search text | `grep_search(SearchPath, Query, IsRegex, Includes)` | `run_command("rg ...")` |
-| List directory | `list_dir(DirectoryPath)` | `run_command("ls ...")` |
-| Execute shell | `run_command(CommandLine, Cwd, WaitMsBeforeAsync)` | n/a |
-| Web search | `search_web(query, domain)` | n/a |
-| Ask user | `ask_question(questions=[{question, options, is_multi_select}])` | n/a |
-
-Always pass `Cwd` to `run_command`; do not rely on inherited shell cwd. On Windows, set UTF-8 in PowerShell before chained commands:
-
-```powershell
-[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
-[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
-chcp 65001 > $null
-```
-
-## Sub-Agent Orchestration (Two Phases)
+## Explore Priority
 
-Antigravity uses an explicit two-phase model for sub-agents — unlike Claude's single `Agent(...)` call:
+`maestro explore` takes priority over Glob, Grep, and Read. When locating files or searching code patterns, call `maestro explore` first and stop to wait for results.
 
-1. **Define**: declare the sub-agent type once per session (idempotent within a session)
-   ```
-   define_subagent(
-     name="team-worker",
-     description="Generic role-spec worker",
-     system_prompt="<contents of antigravity-cli/agents/team-worker.md>",
-     enable_write_tools=true,
-     enable_mcp_tools=true,
-     enable_subagent_tools=false
-   )
-   ```
+# Coding Philosophy
 
-2. **Invoke**: spawn one or more instances; capture the returned ConversationId for later messaging
-   ```
-   invoke_subagent([
-     { TypeName: "team-worker",
-       Role:     "<concrete role label>",
-       Prompt:   "<task-specific instructions>",
-       Workspace: "inherit"            # inherit | branch | share
-     }
-   ])
-   ```
+## Core Beliefs
 
-**Workspace modes**:
-- `inherit` — share the parent's working directory (default; matches Claude semantics)
-- `branch` — independent filesystem branch (useful for parallel waves that must not collide)
-- `share` — explicit cross-worker sharing (rare; use only when workers must atomically see each other's writes)
+- **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/
 
-**Inter-agent messaging**: `send_message(Recipient=<ConversationId>, Message=<text>)`. The Recipient must be a ConversationId returned by `invoke_subagent`, never a role name.
+## Simplicity Means
 
-**Background OS tasks vs sub-agents**: `manage_task` handles `run_command` async instances (list / kill / status / send_input). Do **not** repurpose it for named task tracking — use `.workflow/tasks/<id>.json` files instead.
+- 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
 
-## Cross-Skill Invocation
+## Fix, Don't Hide
 
-Agent-internal chaining uses the **inline-execute** pattern:
+**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
 
-```
-view_file(AbsolutePath="<agy-skills-dir>/<target-skill>/SKILL.md") + execute inline (args: "...")
-```
+**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
 
-`<agy-skills-dir>` resolves to:
-- global install: `~/.gemini/antigravity-cli/skills/`
-- workspace install: `<project>/.agents/skills/`
+**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
 
-The agent reads the target SKILL.md, treats its body as additional instructions, and executes them in the same conversation context. Args are passed conceptually as input variables — substitute them when running the loaded instructions.
+## Learning the Codebase
 
-User-initiated invocation uses `/skills`.
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
 
-## Cross-Worker Coordination
+## Tooling
 
-Antigravity has no built-in message bus. For shared logs across workers, write JSONL lines to `.workflow/.team/<session>/.msg/messages.jsonl`:
+- 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
 
-- Log:   `write_to_file(TargetFile=".workflow/.team/<session>/.msg/messages.jsonl", CodeContent="<json line>\n", Overwrite=false)`
-- Read:  `view_file(AbsolutePath=".workflow/.team/<session>/.msg/messages.jsonl")` then filter client-side
-- Status snapshot: write `<session>/.msg/state.json` and read with `view_file`
+## Content Uniqueness Rules
 
-For point-to-point delivery, use `send_message` directly.
+- **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
 
-## Code Diagnostics
+# Context Requirements
 
-- **Prefer `mcp__ide__getDiagnostics`** for code error checking over shell-based TypeScript compilation when the MCP channel is available.
+Before implementation, always:
+- Identify 3+ existing similar patterns
+- Map dependencies and integration points
+- Understand testing framework and coding conventions
 
 ## Knowledge System
 
-### Search — Query Before Acting
+**Gate rule: On any coding/modification/debugging task, run `maestro search` + `maestro load` BEFORE reading code or editing files.**
+
+### Required (every task, no exceptions)
+
+```bash
+# Search relevant knowledge (1-3 keywords, multiple short queries beat one long one)
+maestro search "<topic phrase>"
+
+# Load specs for the task type
+maestro load --type spec --category coding    # coding tasks
+maestro load --type spec --category arch      # architecture decisions
+maestro load --type spec --category test      # test writing
+maestro load --type spec --category ui        # UI work
+```
+
+**Query rules:**
+- Use **1-3 core keywords** per query — never dump all context into one search
+- Separate concepts from symbols: `maestro search "topology layout"` + `maestro search "DetailedTopologySVG" --code`
+- Add as needed: `maestro search "query" --kg` (KG full-source), `maestro kg callers <fn>` (call chain), `maestro kg context <node>` (node context)
+
+```bash
+# ❌ Bad: keyword dump
+maestro search "topology display frontend DetailedTopologySVG elk"
 
-**Before planning or implementing any task, search wiki and spec first** — the knowledge base contains reusable methods, tools, and hard-won experience. Load the right knowledge at the right time: search before you plan, load relevant entries before you implement, and revisit when you hit unfamiliar territory mid-task.
+# ✅ Good: targeted multi-search + spec load
+maestro search "topology layout"
+maestro search "DetailedTopologySVG" --code
+maestro load --type spec --category coding
+```
+
+### Load & Search reference
+
+```bash
+maestro load --type <type> [--list] [--category <cat>] [--keyword <word>] [--id <id>]
+maestro search "<query>" [--type <type>] [--category <cat>] [--code] [--kg] [--json]
+```
+
+**`--category` values** (for `--type spec`): `coding`, `arch`, `debug`, `test`, `review`, `learning`, `ui`
+**`--keyword`**: free-text filter on title/body/tags — use to narrow within a category
+
+**`--type` values**: `spec`, `knowhow`, `domain`, `issue`, `session`, `scratch`, `note`, `project`, `roadmap`
 
-When tackling unfamiliar domains or cross-cutting concerns, search existing knowledge first:
-- `maestro spec load --category <cat>` — load rules by category (coding/arch/debug/test/review/learning)
-- `maestro spec load --keyword <kw>` — cross-category keyword match
-- `maestro wiki search "<query>"` — full-text search across all knowhow
-- `maestro wiki list --category <cat>` → `maestro wiki load <id>` — browse then load full detail
+| Action | Command |
+|--------|---------|
+| Load coding specs | `maestro load --type spec --category coding` |
+| Load arch specs with keyword | `maestro load --type spec --category arch --keyword auth` |
+| List sessions | `maestro load --type session --list` |
+| Load specific knowhow | `maestro load --type knowhow --id <id>` |
+| Search sessions | `maestro search "query" --type session` |
+| Code graph search | `maestro search "symbol" --code` |
+| KG full-source search | `maestro search "query" --kg` |
 
-### Record — Capture Knowledge
+### Record
 
-When execution surfaces non-obvious knowledge (decisions, root causes, pitfalls, patterns), persist it:
+| What | Command |
+|------|---------|
+| Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
+| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` to bridge into agent injection) |
+
+Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
+
+### Confidence & Conflict Marking
+
+When search results conflict with current context, **mark the entry**:
+
+```bash
+maestro spec conflict mark <file> <line> --note "<reason>"
+maestro spec conflict list
+```
 
-- **Spec entry** (short rule/constraint) → `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"`
-- **Knowhow document** (detailed recipe/template/decision/reference) → `/manage-knowhow-capture`
+Levels: `high` (verified) → `medium` (default) → `low` (stale) → `contested` (conflict detected).
 
-Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, test strategy→`test`.
+- `contested` → sorted last during injection, labeled `[CONTESTED]` with conflict note
+- `low` → labeled `[LOW CONFIDENCE]`
+- Resolution handled by `/manage-knowledge-audit`

package/workflows/analyze.md

@@ -316,7 +316,7 @@ Append initial Intent Coverage Check to discussion.md.
 
 **Step 4.6: Baseline Confidence Scoring**
 
-Dimensions = the 6 analysis dimensions. Factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each factor per dimension from Round 1 results. Append baseline confidence table to discussion.md. Thresholds: <60% 继续深入 | 60-80% 需用户确认收敛 | >80% 建议收敛.
+Dimensions = the 6 analysis dimensions. Factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each factor per dimension from Round 1 results. Append baseline confidence table to discussion.md. Thresholds: <60% 继续深入 | 60-80% 需用户确认收敛 | >80% → proceed to synthesis (REQUIRED convergence threshold).
 
 ### Step 5: Interactive Discussion Loop
 
@@ -764,7 +764,7 @@ Replaceable blocks (overwritten each round):
 | Error | Resolution |
 |-------|------------|
 | cli-explore-agent fails | Retry once. If still fails: log W001 warning in discussion.md, flag all subsequent decisions as LOW CONFIDENCE (evidence gap), continue with available context |
-| CLI timeout | Retry with shorter prompt, or skip perspective |
+| CLI timeout | Retry with shorter prompt; if still fails, mark perspective [LOW CONFIDENCE] (evidence gap) in discussion.md and continue |
 | Max rounds reached | Force synthesis, offer continuation |
 | No relevant findings | Broaden search, ask user for clarification |
 | Session folder conflict | Append timestamp suffix |

package/workflows/auto-test.md

@@ -26,6 +26,7 @@ Only Step 2 diverges (scenario source). Everything else is shared.
 
 **Load specs:**
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_test = maestro spec load --category test
 specs_arch = maestro spec load --category arch
 ```
@@ -348,7 +349,7 @@ Build layer-L{N}-write.csv:
   prev_context = findings from completed prior-layer scenarios (cross-layer propagation)
 ```
 
-#### 5b. Parallel Test Writing via spawn_agents_on_csv
+#### 5b. Parallel Test Writing via spawn_agents_on_csv — MANDATORY, NOT SUBSTITUTABLE
 
 ```javascript
 spawn_agents_on_csv({
@@ -385,6 +386,8 @@ Merge write-results into master state. Delete temp CSV. Proceed to next layer or
 
 **If `--max-iter 1`:** After all layers written and run once, jump directly to Step 8 (single-pass mode, replaces test-gen behavior). Skip Steps 6-7.
 
+**GATE Step 5→6**: write-results merged into master state BEFORE execution; REQUIRED: `.tests/auto-test/.csv-session/layer-L*-write-results.csv` merged and temp CSV deleted; BLOCKED if write-results missing or unmerged.
+
 ---
 
 ### Step 6: Execute (Progressive Layers)
@@ -424,6 +427,7 @@ OUTER LOOP (max_iter iterations):
          Build diagnosis-iter-{N}.csv:
            Columns: id, scenario_id, layer, test_file, error_detail, expected, actual, target_file, source_context
 
+         # MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
          spawn_agents_on_csv({
            csv_path: `.tests/auto-test/.csv-session/diagnosis-iter-${iter}.csv`,
            id_column: "id",
@@ -612,6 +616,8 @@ Scored after each REFLECT step. Dimensions (5): scenario_coverage, test_quality,
 | `.tests/business/business-test-report.json` | `.tests/auto-test/report.json` (source_route: "spec") |
 | `.tests/business/business-test-summary.md` | `.tests/auto-test/traceability.md` (conditional) |
 
+**GATE Step 8→9**: Glob `.tests/auto-test/report.json` MUST exist before Step 9 post-processing; BLOCKED if missing.
+
 ---
 
 ### Step 9: Post-Processing & Routing

package/workflows/blueprint.md

@@ -14,6 +14,9 @@ brainstorm (parallel) → blueprint → analyze → plan
 P0: Spec Study → P1: Discovery → P1.5: Req Expansion → P2: Product Brief → P3: PRD → P4: Architecture → P5: Epics → P6: Readiness Check
 
 P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail (<60%) → P6.5 Auto-Fix (max 2 iter) → re-check
+
+GATE P2→P3: REQUIRED `product-brief.md` written with ≥5 glossary terms in `glossary.json`; BLOCKED if `product-brief.md` missing or glossary < 5 terms.
+GATE P3→P4: REQUIRED `requirements/_index.md` written with MoSCoW priority table; BLOCKED if `_index.md` missing or MoSCoW table absent.
 ```
 
 ## Arguments
@@ -103,7 +106,7 @@ Session ID: BLP-{slug}-{YYYY-MM-DD}
 Output dir: .workflow/blueprint/{session_id}/
 ```
 
-**Step 2.3: Seed Analysis via CLI**
+**Step 2.3: Seed Analysis via CLI** — MANDATORY, NOT SUBSTITUTABLE
 - Spawn CLI analysis to extract: problem_statement, target_users, domain, constraints, dimensions (3-5)
 - Assess complexity: simple (1-2 components) / moderate (3-5) / complex (6+)
 - For context-package input: enrich with feature decomposition data
@@ -160,7 +163,7 @@ Generate product brief through multi-perspective CLI analysis.
 - Read discovery-context.json (if codebase detected)
 - For context-package input: read context-package.json domain and requirements sections
 
-**Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)**
+**Step 4.2: Multi-CLI Parallel Analysis (3 perspectives)** — MANDATORY, NOT SUBSTITUTABLE
 
 | Perspective | Role | Focus |
 |-------------|------|-------|
@@ -189,7 +192,7 @@ Generate product brief through multi-perspective CLI analysis.
 
 Generate detailed PRD with functional/non-functional requirements.
 
-**Step 5.1: Requirement Expansion via CLI**
+**Step 5.1: Requirement Expansion via CLI** — MANDATORY, NOT SUBSTITUTABLE
 - For each product brief goal, generate 3-7 functional requirements
 - Each requirement: REQ-NNN ID, title, description, user story, 2-4 acceptance criteria
 - Generate non-functional requirements: performance, security, scalability, usability
@@ -214,12 +217,12 @@ Generate detailed PRD with functional/non-functional requirements.
 
 Generate architecture decisions, component design, and technology selections.
 
-**Step 6.1: Architecture Analysis via CLI (role: review)**
+**Step 6.1: Architecture Analysis via CLI (role: review)** — MANDATORY, NOT SUBSTITUTABLE
 - System architecture style with justification
 - Core components and responsibilities
 - Component interaction diagram (Mermaid graph TD)
 - Technology stack: languages, frameworks, databases, infrastructure
-- 2-4 Architecture Decision Records (ADRs): context, decision, alternatives, consequences
+- 2-4 Architecture Decision Records (ADRs): context, decision, alternatives, consequences, evidence_source
 - Data model: entities and relationships (Mermaid erDiagram)
 - Security architecture: auth, authorization, data protection
 - **State machine**: ASCII diagram + transition table for lifecycle entities (service/platform type)
@@ -230,7 +233,7 @@ Generate architecture decisions, component design, and technology selections.
 - Glossary injection for terminology consistency
 - If `apiResearchContext` is set: inject as "External API Research" context
 
-**Step 6.2: Architecture Review via CLI (role: review)**
+**Step 6.2: Architecture Review via CLI (role: review)** — MANDATORY, NOT SUBSTITUTABLE
 - Challenge each ADR, identify scalability bottlenecks
 - Assess security gaps, evaluate technology choices
 - Rate overall quality 1-5
@@ -252,7 +255,7 @@ Generate architecture decisions, component design, and technology selections.
 
 Decompose specification into executable Epics and Stories.
 
-**Step 7.1: Epic Decomposition via CLI**
+**Step 7.1: Epic Decomposition via CLI** — MANDATORY, NOT SUBSTITUTABLE
 - Group requirements into logical Epics (EPIC-NNN IDs). Epic count is unconstrained — downstream workflows will merge Epics into minimal phases via the minimum-phase principle.
 - Tag MVP subset
 - For each Epic: 2-5 Stories in "As a...I want...So that..." format
@@ -280,7 +283,7 @@ Decompose specification into executable Epics and Stories.
 
 Validate specification package and provide execution handoff.
 
-**Step 8.1: Cross-Document Validation via CLI**
+**Step 8.1: Cross-Document Validation via CLI** — MANDATORY, NOT SUBSTITUTABLE
 Score on 4 dimensions (25% each):
 1. **Completeness**: all required sections present with substantive content
 2. **Consistency**: terminology uniform (glossary compliance), scope containment, non-goals respected
@@ -390,14 +393,14 @@ Resume: `-c` reads blueprint-config.json, resumes from first incomplete phase.
 | Phase | Error | Blocking? | Action |
 |-------|-------|-----------|--------|
 | Phase 1 | Empty input | Yes | Error and exit |
-| Phase 1 | CLI analysis fails | No | Basic parsing fallback |
-| Phase 1.5 | Gap analysis fails | No | Skip to basic prompts |
-| Phase 2 | Single CLI fails | No | Continue with available |
-| Phase 3 | Gemini fails | No | Codex fallback |
-| Phase 4 | Review fails | No | Skip review |
-| Phase 5 | Story generation fails | No | Generate epics only |
-| Phase 6 | Validation fails | No | Partial report |
-| Phase 6.5 | Max iterations (2) | No | Force handoff |
-| Step 2.5 | External research fails | No | apiResearchContext = null, continue |
-
-CLI Fallback Chain: Role-based resolution → degraded mode (local only)
+| Phase 1 | CLI analysis fails | No | Basic parsing fallback; flag seed_analysis as [LOW CONFIDENCE] (CLI analysis unavailable) |
+| Phase 1.5 | Gap analysis fails | No | Skip to basic prompts; flag refined-requirements.json as [LOW CONFIDENCE] (no gap analysis) |
+| Phase 2 | Single CLI fails | No | Continue with available; flag product-brief.md as [LOW CONFIDENCE] (missing perspective) |
+| Phase 3 | Gemini fails | No | Codex fallback; flag affected REQ-NNN.md as [LOW CONFIDENCE] (model fallback) |
+| Phase 4 | Review fails | No | Skip review; flag ADR-NNN.md as [LOW CONFIDENCE] (no peer review) |
+| Phase 5 | Story generation fails | No | Generate epics only; flag EPIC-NNN.md stories as [LOW CONFIDENCE] (stories incomplete) |
+| Phase 6 | Validation fails | No | Partial report; flag readiness-report.md as [LOW CONFIDENCE] (validation incomplete) |
+| Phase 6.5 | Max iterations (2) | No | Force handoff; flag readiness-report.md as [LOW CONFIDENCE] (auto-fix exhausted) |
+| Step 2.5 | External research fails | No | apiResearchContext = null, continue; flag apiResearchContext as [LOW CONFIDENCE] (no external research) |
+
+CLI Fallback Chain: Role-based resolution → degraded mode (local only); flag affected phase artifacts as [LOW CONFIDENCE] (CLI unavailable, local-only analysis)

package/workflows/brainstorm.md

@@ -131,7 +131,7 @@ Pre-seed from context-package:
 - `insights[]` → Step 4 role agents
 - `requirements[]` → Step 3 Phase 4.5
 
-W007 if source not found: continue without upstream.
+W007 if source not found: continue without upstream; flag guidance-specification.md as [LOW CONFIDENCE] (no upstream context).
 
 ---
 
@@ -148,7 +148,7 @@ specs_content = maestro spec load --category arch
 **Trigger**: Always in auto mode. Skip if `--skip-questions` and no tech keywords.
 
 ```
-// Step 1.7.1: Spawn external researcher for design routes
+// Step 1.7.1: Spawn external researcher for design routes — MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 Agent(
   subagent_type="workflow-external-researcher",
   prompt="""
@@ -185,7 +185,7 @@ designResearchContext = agent_output
 
 `designResearchContext` → Steps 2, 3, 4. Persisted to `{output_dir}/design-research.md`.
 
-W005 on failure: continue without external context.
+W005 on failure: continue without external context; flag role analyses as [LOW CONFIDENCE] (no design research).
 
 ---
 
@@ -271,6 +271,8 @@ Seven sub-phases producing guidance-specification.md:
 
 **Output**: `{output_dir}/guidance-specification.md`, session metadata (workflow-session.json)
 
+**GATE Step 3→4**: REQUIRED `guidance-specification.md` written with §10 Feature Decomposition list; BLOCKED if `guidance-specification.md` missing or §10 feature list absent.
+
 ### Step 3.5: Visual Style Foundation (Auto Mode, conditional)
 
 **Condition**: `ui-designer` selected AND `.workflow/impeccable/DESIGN.md` does not exist. Skip with `--skip-design`.
@@ -286,6 +288,7 @@ Seven sub-phases producing guidance-specification.md:
 Spawn `role-design-author` per role in parallel. ALWAYS use absolute paths. Pass `null` (literal string) for absent optional fields.
 
 ```
+// MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 Agent({
   subagent_type: "role-design-author",
   prompt: """
@@ -323,11 +326,14 @@ Agent({
 - §4: listed files exist on disk, feature coverage matches
 - system-architect: §3 has "Data Model" and "State Machine" headings
 
+**GATE Step 4→4.5**: REQUIRED all `{role}/analysis.md` verified on disk via Glob (per role in selected_roles); BLOCKED if any `analysis.md` missing.
+
 ### Step 4.5: Cross-Role Review (Auto Mode)
 
 Spawn ONE `cross-role-reviewer` to compare Decision Digests across roles.
 
 ```
+// MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 Agent({
   subagent_type: "cross-role-reviewer",
   prompt: """
@@ -498,3 +504,5 @@ Write `{output_dir}/context-package.json` by extracting from session artifacts:
 Register artifact in state.json with additional field:
   `context_package: "{output_dir}/context-package.json"`   (relative to .workflow/)
 
+**GATE Step 7.5→complete**: Glob `{output_dir}/context-package.json` MUST exist before workflow report; BLOCKED if missing.
+

package/workflows/business-test.md

@@ -232,6 +232,8 @@ Wait for user confirmation. If "edit": let user modify plan interactively.
 
 ---
 
+**GATE Step 4→5**: REQUIRED `business-test-plan.json` written and user-confirmed before test generation; BLOCKED if plan missing or unconfirmed.
+
 ### Step 5: Generate Test Code (if --gen-code)
 
 **Detect project tech stack:**
@@ -487,6 +489,8 @@ Update `index.json` with business_test section:
 
 ---
 
+**GATE Step 8→9**: Glob `${PHASE_DIR}/.tests/business/business-test-report.json` MUST exist before Step 9 issue creation; BLOCKED if missing.
+
 ### Step 9: Feedback Loop
 
 **Auto-create issues from failures:**

package/workflows/codebase-rebuild.md

@@ -61,6 +61,7 @@ Build component entry:
 ### Step 2.5: Load Project Specs
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_content = maestro spec load --category arch
 ```
 
@@ -115,7 +116,8 @@ map to components by keyword analysis. Build ADR entry:
     "title": "{ADR title}",
     "component_ids": ["TC-{NNN}"],
     "decision": "{decision summary}",
-    "rationale": "{rationale summary}"
+    "rationale": "{rationale summary}",
+    "evidence_source": "{evidence source — ADR file ref or code anchor}"
   }
 
 If no ADRs: architecture_decisions = [].
@@ -141,6 +143,8 @@ Assemble the complete doc-index.json:
 Write to: .workflow/codebase/doc-index.json
 ```
 
+**GATE Step 6→7**: REQUIRED `doc-index.json` written and valid JSON before tech-registry generation; BLOCKED if `doc-index.json` missing or invalid.
+
 ### Step 7: Generate Tech Registry Docs
 
 ```
@@ -177,6 +181,8 @@ b. Update project.md Tech Stack (if exists):
    If changes detected: update section + footer timestamp.
 ```
 
+**GATE Step 8.5→9**: Glob `.workflow/codebase/doc-index.json` AND `.workflow/codebase/knowledge-graph.json` MUST exist before Step 9 report; BLOCKED if missing.
+
 ### Step 9: Report and Commit
 
 ```
@@ -201,6 +207,7 @@ Uses the native `maestro kg index` command (`src/graph/analyzers/fs-analyzer.ts`
 ### Step 10: Generate Knowledge Graph
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 maestro kg index --src "$PROJECT_ROOT/src"
 ```
 

package/workflows/codebase-refresh.md

@@ -52,6 +52,7 @@ Build affected sets:
 ### Step 3.5: Load Project Specs
 
 ```
+# MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep
 specs_content = maestro spec load --category arch
 ```
 
@@ -61,6 +62,7 @@ Used in Step 4-5 to validate refreshed docs against architectural expectations.
 
 ```
 If .workflow/codebase/knowledge-graph.json exists:
+  # MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep (when KG exists)
   Run: maestro kg diff-wiki --json
   Parse output for affectedWiki entries.
 
@@ -74,7 +76,7 @@ If .workflow/codebase/knowledge-graph.json exists:
     {affectedWiki.length} wiki entries flagged"
 
 If .workflow/codebase/knowledge-graph.json does not exist:
-  Skip silently (KG not generated).
+  Log W0xx "KG not generated — KG impact analysis skipped" and continue; flag KG analysis as [LOW CONFIDENCE] (KG unavailable).
 ```
 
 ---
@@ -92,6 +94,8 @@ If --deep: follow reverse dependency chain to find additional affected component
 Report new files matching component naming patterns (do not auto-add).
 ```
 
+**GATE Step 4→5**: REQUIRED affected components re-scanned (symbols[] and last_updated refreshed) before relationship check; BLOCKED if affected components not re-scanned.
+
 ### Step 5: Check Relationship Changes
 
 ```
@@ -126,6 +130,8 @@ If entries changed: regenerate tech-registry/_index.md and feature-maps/_index.m
 Update .workflow/state.json: set codebase_last_refreshed and last_updated timestamps.
 ```
 
+**GATE Step 8→9**: Glob refreshed `tech-registry/{slug}.md` MUST exist before Step 9 report; BLOCKED if missing.
+
 ### Step 9: Report
 
 ```

package/workflows/codex-instructions.md

@@ -141,7 +141,7 @@ maestro search "<query>" [--type <type>] [--category <cat>] [--code] [--kg] [--j
 | What | Command |
 |------|---------|
 | Spec | `/spec-add <category> "title" "content" --keywords kw1,kw2 --description "summary"` |
-| Knowhow | Persist non-obvious knowledge (deviations, root causes, constraints) |
+| Knowhow | `/manage-knowhow-capture` (`--spec-category <cat>` to bridge into agent injection) |
 
 Category routing: decisions→`arch`, patterns→`coding`, pitfalls→`debug`/`learning`, rules→`review`, tests→`test`.
 

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
 
 ```