maestro-flow 0.5.37 → 0.5.38

package/workflows/spec-generate.md

@@ -2,7 +2,7 @@
 
 Specification document chain producing a complete specification package (Product Brief, PRD, Architecture, Epics, Roadmap) through 7 sequential phases with multi-CLI analysis and interactive refinement. Pure documentation — no code generation.
 
-**Shared logic**: `@roadmap-common.md` (worktree guard, context loading, codebase exploration, external research, minimum-phase principle, roadmap write logic)
+**Shared logic**: `@~/.maestro/workflows/roadmap-common.md` (worktree guard, context loading, codebase exploration, external research, minimum-phase principle, roadmap write logic)
 
 ## Pipeline Position
 
@@ -70,7 +70,7 @@ Load specification and template documents:
 | Quality gates | Per-phase quality criteria and scoring | P0 - must read |
 | Templates | product-brief, requirements-prd, architecture-doc, epics-template | Read on-demand per phase |
 
-**Load project specs and history**: Follow roadmap-common.md "Load Project Context".
+**Load project specs and history**: MANDATORY: execute ~/.maestro/workflows/roadmap-common.md "Load Project Context"; REQUIRED produce: specs+history loaded.
 
 Additional full-mode rules:
 - Features in `already_shipped` are EXCLUDED from spec generation scope
@@ -109,15 +109,15 @@ Session ID: SPEC-{slug}-{YYYY-MM-DD}
 Output dir: .workflow/.spec/{session_id}/
 ```
 
-**Step 2.3: Seed Analysis via CLI**
+**Step 2.3: Seed Analysis via CLI** (MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep)
 - 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
 
-**Step 2.4: Codebase Exploration** — follow roadmap-common.md
+**Step 2.4: Codebase Exploration** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md Codebase Exploration logic; REQUIRED produce: discovery-context.json (codebase context)
 - Output: `discovery-context.json` with relevant_files, patterns, tech_stack
 
-**Step 2.5: External Research** — follow roadmap-common.md
+**Step 2.5: External Research** — MANDATORY: execute ~/.maestro/workflows/roadmap-common.md External Research logic; REQUIRED produce: apiResearchContext (or [LOW CONFIDENCE] if none)
 
 `apiResearchContext` is passed into:
 - Step 4 (Product Brief): technology feasibility assessment
@@ -166,7 +166,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 by manual Read/Grep)
 
 | Perspective | Role | Focus |
 |-------------|------|-------|
@@ -191,6 +191,8 @@ Generate product brief through multi-perspective CLI analysis.
 
 **Output**: `product-brief.md`, `glossary.json`
 
+**GATE P2→P3**: REQUIRED product-brief.md written; BLOCKED if missing
+
 ### Step 5: Requirements / PRD (Phase 3)
 
 Generate detailed PRD with functional/non-functional requirements.
@@ -216,11 +218,13 @@ Generate detailed PRD with functional/non-functional requirements.
 
 **Output**: `requirements/` directory (index + individual files)
 
+**GATE P3→P4**: REQUIRED requirements/_index.md with MoSCoW table; BLOCKED if missing
+
 ### Step 6: Architecture (Phase 4)
 
 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 by manual Read/Grep)
 - System architecture style with justification
 - Core components and responsibilities
 - Component interaction diagram (Mermaid graph TD)
@@ -340,7 +344,7 @@ Convert Epics into an interactive roadmap with user confirmation.
 - Read individual `EPIC-NNN-{slug}.md` for Stories and acceptance criteria
 - Read `architecture/_index.md` for technical constraints (ADR decisions)
 
-Apply **Minimum-Phase Principle** from roadmap-common.md for Epic→Phase mapping:
+Apply **Minimum-Phase Principle** from ~/.maestro/workflows/roadmap-common.md for Epic→Phase mapping:
 - Default: ALL Epics → 1 Phase (wave DAG orders tasks by Epic dependencies)
 - Only split if hard dependency conditions are all met
 - MVP-tagged Epics → Milestone 1, Post-MVP → Milestone 2+
@@ -350,7 +354,7 @@ Apply **Minimum-Phase Principle** from roadmap-common.md for Epic→Phase mappin
 - ADR decisions → phase technical constraints
 
 **Step 11.2: Generate Draft Roadmap**
-Follow roadmap-common.md **Roadmap Template** format. For full mode, populate from product-brief.md vision and Epic→Stories acceptance criteria.
+MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **Roadmap Template** format. For full mode, populate from product-brief.md vision and Epic→Stories acceptance criteria; REQUIRED produce: roadmap section.
 
 **Step 11.3: Interactive Refinement (max 3 rounds)**
 - Present roadmap overview: phase count, milestone structure, dependency graph
@@ -364,9 +368,9 @@ Follow roadmap-common.md **Roadmap Template** format. For full mode, populate fr
 
 **Step 11.4: Write Outputs**
 - Write `roadmap.md` to spec directory: `{spec_dir}/roadmap.md`
-- Write `.workflow/roadmap.md` — follow roadmap-common.md **Overwrite vs Edit Rules**
+- MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **Overwrite vs Edit Rules**; REQUIRED produce: .workflow/roadmap.md; BLOCKED if missing
 - Update `spec-config.json`: add Phase 7 completion
-- Update `state.json` — follow roadmap-common.md **state.json Update Rules**
+- MANDATORY: apply ~/.maestro/workflows/roadmap-common.md **state.json Update Rules**; REQUIRED produce: state.json updated
 
 **Step 11.5: Handoff Options (AskUserQuestion)**
 
@@ -380,6 +384,7 @@ Follow roadmap-common.md **Roadmap Template** format. For full mode, populate fr
 ### Step 12: Final Report
 
 ```
+Glob product-brief.md AND requirements/ AND architecture/ AND epics/ MUST exist before final report; BLOCKED if missing.
 == spec-generate complete ==
 Session: SPEC-{slug}-{date} | Quality: {score}% ({gate}) | Phases: {completed_count}/7
 Output: .workflow/.spec/{session_id}/
@@ -457,14 +462,14 @@ Init detects existing `.workflow/roadmap.md` and skips roadmap creation.
 | Phase | Error | Blocking? | Action |
 |-------|-------|-----------|--------|
 | Phase 1 | Empty input | Yes | Error and exit |
-| Phase 1 | CLI analysis fails | No | Basic parsing fallback |
+| Phase 1 | CLI analysis fails | No | Basic parsing fallback; flag seed analysis as [LOW CONFIDENCE] (basic parsing) |
 | 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 2 | Single CLI fails | No | Continue with available; flag product-brief as [LOW CONFIDENCE] (N-1 perspectives) |
+| Phase 3 | Gemini fails | No | Codex fallback; flag requirements as [LOW CONFIDENCE] (fallback tool) |
+| Phase 4 | Review fails | No | Skip review; flag architecture/ as [LOW CONFIDENCE] (review skipped) |
 | Phase 5 | Story generation fails | No | Generate epics only |
-| Phase 6 | Validation fails | No | Partial report |
+| Phase 6 | Validation fails | No | Partial report; flag readiness-report as [LOW CONFIDENCE] (validation incomplete) |
 | Phase 6.5 | Max iterations (2) | No | Force handoff |
-| Step 2.5 | External research fails | No | apiResearchContext = null, continue |
+| Step 2.5 | External research fails | No | apiResearchContext = null, continue; flag Phase 2-5 outputs as [LOW CONFIDENCE] (no external research) |
 
-CLI Fallback Chain: Role-based resolution → degraded mode (local only)
+CLI Fallback Chain: Role-based resolution → degraded mode (local only); flag all affected outputs as [LOW CONFIDENCE] (degraded local-only mode)

package/workflows/specs-load.md

@@ -59,7 +59,7 @@ Extract `--scope`, `--uid`, `--category <category>` and remaining text (keyword
 maestro spec load --scope <scope> [--uid <uid>] [--category <category>] [--keyword <word>]
 ```
 
-If `maestro spec load` CLI is unavailable, read files directly from the resolved directory.
+If `maestro spec load` CLI is unavailable, read files directly from the resolved directory; flag loaded specs as [LOW CONFIDENCE] (CLI unavailable, direct file read).
 
 ### Step 3: Keyword Filter (optional)
 

package/workflows/specs-setup.md

@@ -285,6 +285,8 @@ source: spec-setup
 
 ### Step 7: Summary
 
+Glob created spec/recipe files MUST exist before Step 7 summary; BLOCKED if missing.
+
 Display list of all created files grouped by destination:
 
 ```

package/workflows/sync.md

@@ -36,8 +36,8 @@ No files changed → emit W001, exit
 Read .workflow/codebase/doc-index.json
 Extract: components[], features[], requirements[], architecture_decisions[]
 
-If missing: prompt → (a) run /manage-codebase-rebuild then re-run (recommended)
-             or    → (b) DEGRADED_MODE: git-diff-only, skip Steps 3-5
+If missing: prompt → (a) MUST run /manage-codebase-rebuild then re-run
+             or    → (b) DEGRADED_MODE: git-diff-only, skip Steps 3-5; flag sync as [LOW CONFIDENCE] (git-diff-only, Steps 3-5 skipped)
 ```
 
 ### Step 4: Impact Chain Traversal
@@ -50,6 +50,8 @@ Traverse impact chain: file → components (via code_locations match)
 Aggregate deduplicated: { files, components, features, requirements }
 ```
 
+GATE Step 4→5: impact_chain non-empty BEFORE update index; BLOCKED if impact_chain empty (no affected components/features/requirements identified)
+
 ### Step 5: Update Doc Index (skip if --dry-run)
 
 ```

package/workflows/test-gen.md

@@ -12,7 +12,7 @@ Tests expose bugs -- fixing is for quality-debug or maestro-execute.
 specs_content = maestro spec load --category test
 ```
 
-Follow project test conventions in Step 4 (Generate Test Plan) and Step 5 (Write Tests).
+Apply project test conventions (from Step 0 specs) when generating the plan (Step 4) and writing tests (Step 5); REQUIRED: tests conform to loaded spec conventions.
 
 ---
 

package/workflows/test.md

@@ -275,7 +275,7 @@ issues == 0 → Step 13. issues > 0 → Step 11.
 ### Step 11: Auto-Diagnose
 
 1. **Cluster gaps** by component/area (same file/module → one cluster, same flow → one cluster)
-2. **Spawn one debug agent per cluster** (parallel, `run_in_background: false`): pre-filled symptoms, `goal: find_root_cause`. Include `issue_id` refs.
+2. MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: **Spawn one debug agent per cluster** (parallel, `run_in_background: false`): pre-filled symptoms, `goal: find_root_cause`. Include `issue_id` refs.
 3. **Collect results**, update uat.md gaps:
 ```yaml
 - test: {N}

package/workflows/ui-codify-extract.md

@@ -350,6 +350,7 @@ Task(subagent_type="ui-design-agent",
 ```bash
 # Agents run in parallel and write separate output files
 # Each agent generates its own JSON directly
+Glob ${temp_dir}/style-extraction/style-1/design-tokens.json, ${temp_dir}/animation-extraction/animation-tokens.json, ${temp_dir}/layout-extraction/layout-templates.json MUST exist before Phase 2 complete; BLOCKED if missing
 echo "[Phase 2] Parallel agent analysis complete"
 ```
 

package/workflows/ui-codify-knowhow.md

@@ -203,7 +203,7 @@ echo "  knowhow-manifest.json written to ${package_dir}"
 通过 Skill tool 调用 codify-to-knowhow：
 
 ```javascript
-Skill("codify-to-knowhow", args="${package_dir}")
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Skill("codify-to-knowhow", args="${package_dir}")
 ```
 
 等待 codify-to-knowhow 完成。它将：

package/workflows/ui-codify-package.md

@@ -50,7 +50,7 @@ echo "[Phase 3] Token files prepared"
 **Agent Task**:
 
 ```javascript
-Agent(ui-design-agent): `
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): `
   [PREVIEW_SHOWCASE_GENERATION]
   Generate interactive multi-component showcase panel for reference package
 

package/workflows/ui-codify.md

@@ -130,7 +130,7 @@ echo "  Output: $package_dir"
 
 ## Phase 2: Parallel Agent Extraction (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-extract.md` then execute.
+MANDATORY: execute ui-codify-extract.md steps; REQUIRED produce: design-tokens.json, animation-tokens.json, layout-templates.json; BLOCKED if missing.
 
 Variables available to Phase 2:
 - `source_path` — absolute path to source directory
@@ -147,7 +147,7 @@ Phase 2 writes:
 
 ## Phase 3: Reference Package Generation (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-package.md` then execute.
+MANDATORY: execute ui-codify-package.md steps; REQUIRED produce: preview.html, preview.css, token files copied to package_dir; BLOCKED if missing.
 
 Variables available to Phase 3:
 - `temp_dir` — temporary workspace with extraction results
@@ -167,7 +167,7 @@ Phase 3 writes:
 
 ## Phase 4: Knowledge Asset Generation (Deferred)
 
-**Read** `@~/.maestro/workflows/ui-codify-knowhow.md` then execute.
+MANDATORY: execute ui-codify-knowhow.md steps; REQUIRED produce: knowhow-manifest.json, knowhow files, spec entries; BLOCKED if missing.
 
 Variables available to Phase 4:
 - `package_dir` — package directory with all token files
@@ -189,15 +189,17 @@ Phase 4 writes:
 | 1 | E001: Missing source path | Report usage, exit |
 | 1 | E002: Source not found | Report path, exit |
 | 1 | E003: Package exists | Suggest --overwrite, exit |
-| 2 | Agent failure | Report which agent failed, continue with partial results |
+| 2 | Agent failure | Report which agent failed, continue with partial results; flag partial results as [LOW CONFIDENCE] (agent failure) |
 | 2 | No files discovered | Report empty discovery, exit |
 | 3 | Token copy failed | Report missing file, exit |
-| 3 | Preview generation failed | Report error, continue (preview is non-critical) |
-| 4 | Manifest build failed | Report error, package still usable without knowhow |
-| 4 | codify-to-knowhow failed | Report error, manifest remains for manual retry |
+| 3 | Preview generation failed | Report error, continue (preview is non-critical); flag preview.html/css as [LOW CONFIDENCE] (preview generation failed) |
+| 4 | Manifest build failed | Report error, package still usable without knowhow; flag knowhow assets as [LOW CONFIDENCE] (manifest build failed) |
+| 4 | codify-to-knowhow failed | Report error, manifest remains for manual retry; flag knowhow/spec entries as [LOW CONFIDENCE] (codify-to-knowhow failed) |
 
 ## Completion Message
 
+Glob all listed output files MUST exist before completion message; BLOCKED if missing.
+
 ```
 UI Design System Codified!
 

package/workflows/ui-design.md

@@ -124,7 +124,7 @@ python3 "${SKILL_PATH}" "accessibility animation interaction" --domain ux
 #### 3b. Generate design direction options via ui-design-agent
 
 ```
-Agent(ui-design-agent): [DESIGN_DIRECTION_GENERATION]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [DESIGN_DIRECTION_GENERATION]
 
 Generate ${styleCount} maximally contrasting design directions (min 6D distance: 0.7).
 
@@ -152,7 +152,7 @@ Update `analysis-options.json` with `user_selection` field.
 For each selected direction, spawn ui-design-agent:
 
 ```
-Agent(ui-design-agent): [DESIGN_SYSTEM_GENERATION #${variant_index}]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [DESIGN_SYSTEM_GENERATION #${variant_index}]
 
 Generate production-ready design tokens from selected direction.
 Map 6D attributes to token values:
@@ -200,7 +200,7 @@ Requirements: ALL colors OKLCH, WCAG AA (4.5:1 text, 3:1 UI), complete combinati
 **Purpose:** Generate animation system complementing the selected styles.
 
 ```
-Agent(ui-design-agent): [ANIMATION_SYSTEM_GENERATION]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [ANIMATION_SYSTEM_GENERATION]
 
 Input: selected variant's design-tokens.json (mood/weight context) + ui-ux-pro-max UX data.
 Output: ${PHASE_DIR}/design-ref/animation-tokens.json
@@ -227,7 +227,7 @@ Requirements: CSS custom properties, prefers-reduced-motion mandatory, var() ref
 #### 5a. Generate layout concept options
 
 ```
-Agent(ui-design-agent): [LAYOUT_CONCEPT_GENERATION]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [LAYOUT_CONCEPT_GENERATION]
 
 Generate ${layoutCount} structurally distinct layout concepts per target.
 Concepts must differ in: grid structure, component arrangement, visual hierarchy, navigation pattern.
@@ -249,7 +249,7 @@ Update analysis-options.json with `user_selection.selected_variants`.
 For each selected concept × target:
 
 ```
-Agent(ui-design-agent): [LAYOUT_TEMPLATE_GENERATION -- ${target} variant ${variant_id}]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [LAYOUT_TEMPLATE_GENERATION -- ${target} variant ${variant_id}]
 
 Structure ONLY, no visual style. Output: ${PHASE_DIR}/design-ref/layout-templates/layout-${target}-${variant_id}.json
 
@@ -267,6 +267,8 @@ Schema:
 Rules: semantic HTML5, ARIA roles, var() refs only (no hard-coded values), mobile-first responsive. NO colors/fonts/shadows.
 ```
 
+GATE Step 5→6: design-tokens.json + animation-tokens.json + layout-templates exist BEFORE assembly; BLOCKED if any missing
+
 ---
 
 ### Step 6: Assemble HTML Prototypes (Layer 4 — Assembly)
@@ -276,7 +278,7 @@ Rules: semantic HTML5, ARIA roles, var() refs only (no hard-coded values), mobil
 For each `style × layout × target` combination, spawn ui-design-agent:
 
 ```
-Agent(ui-design-agent): [PROTOTYPE_ASSEMBLY -- ${target}-style-${s}-layout-${l}]
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Agent(ui-design-agent): [PROTOTYPE_ASSEMBLY -- ${target}-style-${s}-layout-${l}]
 
 Pure assembly: combine pre-extracted structure + tokens. NO design decisions.
 
@@ -375,7 +377,7 @@ Spacing & Layout, Effects & Interactions, Component Styles, Animation System, An
 | Python not found | Abort with install instructions per OS |
 | ui-ux-pro-max not found | Abort, suggest skill installation |
 | Design system returns empty | Retry with broader keywords, then abort |
-| Prototype agent fails | Log error, continue with other variants |
+| Prototype agent fails | Log error, continue with other variants; flag variants as [LOW CONFIDENCE] (prototype agent failed) |
 | User cancels selection | Save all variants as-is, exit without MASTER.md |
 | --refine without existing design-ref | Error E004 |
 

package/workflows/ui-style.md

@@ -94,6 +94,8 @@ Save variants to `${PHASE_DIR}/design-ref/prototypes/variant-{N}-system.md`.
 Display each variant summary (pattern, colors, typography, effects, anti-patterns).
 User selects: [1-N | "redo" | "all"]. Auto mode selects variant 1.
 
+GATE Step 3→4: selected variant confirmed BEFORE solidification; BLOCKED if no variant selected
+
 ---
 
 ### Step 4: Solidify Selected Design
@@ -109,7 +111,7 @@ python3 "${SKILL_PATH}" "${selected_variant_keywords}" --design-system --persist
 
 #### 4b. Generate design-tokens.json
 
-Spawn agent to extract structured tokens from MASTER.md into `${PHASE_DIR}/design-ref/design-tokens.json`.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn agent to extract structured tokens from MASTER.md into `${PHASE_DIR}/design-ref/design-tokens.json`.
 
 **Token schema keys:** colors (brand/surface/semantic/text/border in OKLCH), typography (family/size/weight/line_height/combinations), spacing, border_radius, shadows, component_styles (button/card/input), breakpoints.
 
@@ -117,7 +119,7 @@ Spawn agent to extract structured tokens from MASTER.md into `${PHASE_DIR}/desig
 
 #### 4c. Generate animation-tokens.json
 
-Spawn agent to generate `${PHASE_DIR}/design-ref/animation-tokens.json` from design-tokens + MASTER.md.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn agent to generate `${PHASE_DIR}/design-ref/animation-tokens.json` from design-tokens + MASTER.md.
 
 **Token schema keys:** duration (instant-slower), easing (ease-out/ease-in-out/spring), transitions, keyframes, interactions (hover states), reduced_motion (prefers-reduced-motion strategy).
 
@@ -140,7 +142,7 @@ Copy `design-system/MASTER.md` and `design-system/pages/*.md` (if generated) to
 
 #### 4f. Optional: Generate HTML prototype
 
-For each target, spawn agent to create `${PHASE_DIR}/design-ref/prototypes/${target}.html` from design-tokens + animation-tokens + MASTER.md.
+For each target, MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: spawn agent to create `${PHASE_DIR}/design-ref/prototypes/${target}.html` from design-tokens + animation-tokens + MASTER.md.
 
 **Rules:** standalone HTML with embedded CSS, realistic content (not lorem ipsum), SVG icons (Heroicons/Lucide CDN), cursor-pointer on clickables, responsive (375/768/1024px), WCAG AA, prefers-reduced-motion.
 
@@ -185,7 +187,7 @@ Same as ui-design.md — plan.md Step 4b detects `design-ref/MASTER.md` and incl
 | Error | Action |
 |-------|--------|
 | ui-ux-pro-max returns empty | Retry with broader keywords, then abort |
-| Token extraction agent fails | Retry once, warn if still fails |
+| Token extraction agent fails | Retry once, warn if still fails; if still fails, mark design-tokens.json as [LOW CONFIDENCE] (token extraction agent failed) |
 | User cancels selection | Save all variants, exit without solidification |
 
 ---

package/workflows/verify.md

@@ -405,7 +405,7 @@ For each success criterion / must-have truth:
 
 ### Step 4: Spawn Auditor Agent (if gaps found)
 
-Spawn workflow-nyquist-auditor agent with gap list, test infrastructure, and phase context.
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Spawn workflow-nyquist-auditor agent with gap list, test infrastructure, and phase context.
 Agent generates missing tests and returns:
 - GAPS FILLED -> record new tests
 - PARTIAL -> record resolved, escalate remainder
@@ -540,10 +540,10 @@ Next steps:
 |-------|--------|
 | Phase directory not found | Abort: "Phase {phase} not found." |
 | No execution results | Abort: "No completed tasks found. Run /workflow:execute first." |
-| No summaries found | Warn, proceed with task file analysis only |
+| No summaries found | Warn, proceed with task file analysis only; flag verification.json as [LOW CONFIDENCE] (partial, summaries missing) |
 | Test framework not detected | Skip coverage calculation, warn user |
-| Coverage command fails | Log error, proceed with requirement mapping only |
-| Verifier agent fails | Retry once, then write partial verification.json |
+| Coverage command fails | Log error, proceed with requirement mapping only; flag validation.json coverage as [LOW CONFIDENCE] (partial, coverage command failed) |
+| Verifier agent fails | Retry once, then write partial verification.json; flag verification.json as [LOW CONFIDENCE] (partial, verifier agent failed) |
 
 ---
 

package/workflows/wiki-connect.md

@@ -39,6 +39,8 @@ Knowledge graph link discovery and health improvement. Analyzes the unified wiki
 
 Gather baseline in parallel via `maestro wiki list --json`, `health`, `orphans`, `hubs --top 10`.
 
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans`, `hubs --top 10`) — use the `maestro wiki` CLI to compute in-degree and orphan sets.
+
 Working state: entry count by type, baseline health score, orphan IDs, hub in-degree counts.
 
 Apply `--scope` filter if provided — restrict all subsequent analysis to matching type.

package/workflows/wiki-digest.md

@@ -74,8 +74,8 @@ Synthesize what these entries collectively teach. Focus on the knowledge pattern
 
 ### Key Entries
 Top 3-5 most important entries by:
-- Hub score (in-degree from `maestro wiki hubs`)
-- Backlink count (from `maestro wiki backlinks <id>`)
+- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Hub score (in-degree from `maestro wiki hubs`)
+- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Backlink count (from `maestro wiki backlinks <id>`)
 - Recency (recently updated entries weigh more)
 
 ### Gap Detection
@@ -93,7 +93,7 @@ Per-theme health adapted from wiki health formula (entries, connectivity, comple
 
 Search via `maestro wiki search` or parse `.workflow/specs/learnings.md` for keyword matches against each theme. Flag **unlinked insights** — learning entries matching a theme but not referenced by any wiki entry in that theme.
 
-If `learnings.md` not found, skip with W002 warning.
+If `learnings.md` not found, skip with W002 warning; mark digest cross-reference as [LOW CONFIDENCE] (learnings.md missing).
 
 ---
 
@@ -152,6 +152,8 @@ Produce `.workflow/knowhow/KNW-digest-{slug}-{YYYY-MM-DD}.md`:
 
 ---
 
+GATE Stage 6→7: gaps identified BEFORE issue routing; BLOCKED if no gaps identified in Stage 5
+
 ## Stage 7: Gap → Issue Routing (if --create-issues)
 
 For each knowledge gap from Stage 5: dedup against `.workflow/issues/issues.jsonl` (same theme + type). If new, append with `type: "knowledge-gap"`, `status: "open"`, `severity: "low"`, `source: "wiki-digest"`, `tags: ["knowledge-gap", "{theme-slug}"]`. Report created count.

package/workflows/wiki-manage.md

@@ -40,6 +40,8 @@ Complements `wiki-connect.md` (link discovery) and `wiki-digest.md` (synthesis)
 
 Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`.
 
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans`, `hubs --top 5`) — use the `maestro wiki` CLI to compute orphan sets and hub in-degree.
+
 ### Step 2: Render Dashboard
 
 Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
@@ -72,6 +74,8 @@ If not `--json`: offer to view an entry by number selection.
 
 Gather baseline via `maestro wiki health`, `orphans --json`, `graph`.
 
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans --json`, `graph`) — use the `maestro wiki` CLI to compute orphans and graph topology.
+
 ### Step 2: Categorize Issues
 
 | Issue Type | Detection | Auto-fix Action |