maestro-flow 0.4.10 → 0.4.12

package/.agents/skills/workflow-skill-designer/phases/04-validation.md

@@ -0,0 +1,471 @@
+# Phase 4: Validation & Integration
+
+Validate the generated skill package for structural completeness, reference integrity, and content quality. Produce a validation report and integration summary.
+
+## Objective
+
+- Verify all required files exist
+- Validate SKILL.md references match actual phase files
+- Check content preservation (for command extraction source)
+- Verify cross-phase data flow consistency
+- Report validation results to user
+
+## Step 4.1: Structural Validation
+
+```javascript
+function validateStructure(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  // Check SKILL.md exists
+  const skillMdExists = fileExists(`${skillDir}/SKILL.md`);
+  if (!skillMdExists) {
+    results.errors.push('SKILL.md not found');
+  }
+
+  // Check all phase files exist
+  for (const phase of config.phases) {
+    const filename = `${String(phase.number).padStart(2, '0')}-${phase.slug}.md`;
+    const filepath = `${skillDir}/phases/${filename}`;
+    if (!fileExists(filepath)) {
+      results.errors.push(`Phase file missing: ${filepath}`);
+    }
+  }
+
+  // Check SKILL.md frontmatter
+  if (skillMdExists) {
+    const skillMd = read_file(`${skillDir}/SKILL.md`);
+    const fm = extractYAMLFrontmatter(skillMd);
+
+    if (!fm.name) results.errors.push('Frontmatter missing: name');
+    if (!fm.description) results.errors.push('Frontmatter missing: description');
+    if (!fm['allowed-tools']) results.errors.push('Frontmatter missing: allowed-tools');
+
+    // Check description has trigger phrase
+    if (fm.description && !fm.description.includes('Triggers on')) {
+      results.warnings.push('Description missing trigger phrase (Triggers on "...")');
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.2: Reference Integrity
+
+```javascript
+function validateReferences(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+  const skillMd = read_file(`${skillDir}/SKILL.md`);
+
+  // Extract all Ref: markers from SKILL.md
+  const refMarkers = skillMd.match(/Ref: phases\/\S+\.md/g) || [];
+  const linkedFiles = skillMd.match(/\[phases\/\S+\.md\]\(phases\/\S+\.md\)/g) || [];
+
+  // Collect all referenced phase files
+  const referencedFiles = new Set();
+  for (const ref of refMarkers) {
+    referencedFiles.add(ref.replace('Ref: ', ''));
+  }
+  for (const link of linkedFiles) {
+    const match = link.match(/\(phases\/\S+\.md\)/);
+    if (match) referencedFiles.add(match[0].replace(/[()]/g, ''));
+  }
+
+  // Check each referenced file exists
+  for (const refFile of referencedFiles) {
+    if (!fileExists(`${skillDir}/${refFile}`)) {
+      results.errors.push(`Referenced file not found: ${refFile}`);
+    }
+  }
+
+  // Check each phase file is referenced in SKILL.md
+  for (const phase of config.phases) {
+    const filename = `phases/${String(phase.number).padStart(2, '0')}-${phase.slug}.md`;
+    if (!referencedFiles.has(filename)) {
+      results.warnings.push(`Phase file not referenced in SKILL.md: ${filename}`);
+    }
+  }
+
+  // Check Phase Reference Documents table exists
+  if (!skillMd.includes('Phase Reference Documents')) {
+    results.errors.push('SKILL.md missing Phase Reference Documents table');
+  }
+
+  // Check Phase Reference Documents table has entries for all phases
+  for (const phase of config.phases) {
+    const filename = `${String(phase.number).padStart(2, '0')}-${phase.slug}.md`;
+    if (!skillMd.includes(filename)) {
+      results.errors.push(`Phase Reference table missing entry for: ${filename}`);
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.3: Content Quality (Command Extraction Only)
+
+```javascript
+function validateContentQuality(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  if (config.source.type !== 'command_set') {
+    results.info.push('Content quality check skipped (not command extraction)');
+    return results;
+  }
+
+  for (const phase of config.phases) {
+    if (!phase.sourcePath) continue;
+
+    const sourceContent = read_file(phase.sourcePath);
+    const sourceBody = removeYAMLFrontmatter(sourceContent);
+    const filename = `${String(phase.number).padStart(2, '0')}-${phase.slug}.md`;
+    const phaseContent = read_file(`${skillDir}/phases/${filename}`);
+
+    // Line count comparison
+    const sourceLines = sourceBody.split('\n').length;
+    const phaseLines = phaseContent.split('\n').length;
+    const ratio = phaseLines / sourceLines;
+
+    if (ratio < 0.7) {
+      results.errors.push(
+        `Phase ${phase.number} content loss: source=${sourceLines} lines, phase=${phaseLines} lines (${Math.round(ratio * 100)}%)`
+      );
+    } else if (ratio < 0.9) {
+      results.warnings.push(
+        `Phase ${phase.number} possible content reduction: source=${sourceLines}, phase=${phaseLines} (${Math.round(ratio * 100)}%)`
+      );
+    } else {
+      results.info.push(
+        `Phase ${phase.number} content preserved: source=${sourceLines}, phase=${phaseLines} (${Math.round(ratio * 100)}%)`
+      );
+    }
+
+    // Code block count comparison
+    const sourceBlocks = (sourceBody.match(/```/g) || []).length / 2;
+    const phaseBlocks = (phaseContent.match(/```/g) || []).length / 2;
+    if (phaseBlocks < sourceBlocks) {
+      results.warnings.push(
+        `Phase ${phase.number} missing code blocks: source=${sourceBlocks}, phase=${phaseBlocks}`
+      );
+    }
+
+    // Agent prompt preservation
+    const sourceAgents = (sourceBody.match(/Task\(|subagent_type/g) || []).length;
+    const phaseAgents = (phaseContent.match(/Task\(|subagent_type/g) || []).length;
+    if (phaseAgents < sourceAgents) {
+      results.errors.push(
+        `Phase ${phase.number} missing agent calls: source=${sourceAgents}, phase=${phaseAgents}`
+      );
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.4: Data Flow Consistency
+
+```javascript
+function validateDataFlow(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+  const skillMd = read_file(`${skillDir}/SKILL.md`);
+
+  // Check all data flow variables are mentioned in SKILL.md
+  for (const flow of config.dataFlow) {
+    for (const variable of flow.variables) {
+      if (!skillMd.includes(variable)) {
+        results.warnings.push(
+          `Data flow variable '${variable}' (${flow.from} → ${flow.to}) not found in SKILL.md`
+        );
+      }
+    }
+  }
+
+  // Check conditional phases have their condition in SKILL.md
+  for (const phase of config.phases) {
+    if (phase.isConditional && phase.condition) {
+      // Extract the key variable from condition
+      const condVar = phase.condition.match(/\w+/)?.[0];
+      if (condVar && !skillMd.includes(condVar)) {
+        results.errors.push(
+          `Conditional Phase ${phase.number} condition variable '${condVar}' not found in SKILL.md`
+        );
+      }
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.5: SKILL.md Section Completeness
+
+```javascript
+function validateSkillMdSections(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+  const skillMd = read_file(`${skillDir}/SKILL.md`);
+
+  // Required sections
+  const requiredSections = [
+    { name: 'Architecture Overview', pattern: /## Architecture Overview/ },
+    { name: 'Execution Flow', pattern: /## Execution Flow/ },
+    { name: 'Core Rules', pattern: /## Core Rules/ },
+    { name: 'Data Flow', pattern: /## Data Flow/ },
+    { name: 'Error Handling', pattern: /## Error Handling/ }
+  ];
+
+  // Recommended sections
+  const recommendedSections = [
+    { name: 'Key Design Principles', pattern: /## Key Design Principles/ },
+    { name: 'Input Processing', pattern: /## Input Processing/ },
+    { name: 'track_tasks Pattern', pattern: /## track_tasks Pattern/ },
+    { name: 'Coordinator Checklist', pattern: /## Coordinator Checklist/ },
+    { name: 'Related Commands', pattern: /## Related Commands/ }
+  ];
+
+  // Conditional sections
+  const conditionalSections = [
+    { name: 'Interactive Preference Collection', pattern: /## Interactive Preference Collection/, condition: config.features.hasAutoMode },
+    { name: 'Auto Mode Defaults', pattern: /## Auto Mode Defaults/, condition: config.features.hasAutoMode },
+    { name: 'Post-Phase Updates', pattern: /## Post-Phase Updates/, condition: config.features.hasPostPhaseUpdates }
+  ];
+
+  for (const section of requiredSections) {
+    if (!section.pattern.test(skillMd)) {
+      results.errors.push(`Missing required section: ${section.name}`);
+    }
+  }
+
+  for (const section of recommendedSections) {
+    if (!section.pattern.test(skillMd)) {
+      results.warnings.push(`Missing recommended section: ${section.name}`);
+    }
+  }
+
+  for (const section of conditionalSections) {
+    if (section.condition && !section.pattern.test(skillMd)) {
+      results.warnings.push(`Missing conditional section: ${section.name} (feature enabled but section absent)`);
+    }
+  }
+
+  return results;
+}
+```
+
+## Step 4.6: Phase File Hygiene
+
+Scan generated phase files for prohibited content patterns. Phase files are internal execution documents and must not contain user-facing syntax, flag parsing, or inter-phase routing.
+
+```javascript
+function validatePhaseFileHygiene(config) {
+  const skillDir = `.claude/skills/${config.skillName}`;
+  const results = { errors: [], warnings: [], info: [] };
+
+  const prohibitedPatterns = [
+    {
+      name: 'Flag parsing ($ARGUMENTS)',
+      regex: /\$ARGUMENTS\.includes/g,
+      severity: 'error',
+      fix: 'Replace with workflowPreferences.{key} reference'
+    },
+    {
+      name: 'Invocation syntax (/skill-name)',
+      regex: /\/\w+[\-:]\w+\s+["']/g,
+      severity: 'warning',
+      fix: 'Remove (phase files are not user-facing docs)'
+    },
+    {
+      name: 'Conversion provenance (Source: Converted from)',
+      regex: /Source:.*Converted from/g,
+      severity: 'warning',
+      fix: 'Remove (implementation detail)'
+    },
+    {
+      name: 'Skill routing for inter-phase (invoke_skill(skill=...)',
+      regex: /Skill\(skill=/g,
+      severity: 'error',
+      fix: 'Replace with direct read_file("phases/0N-xxx.md")'
+    },
+    {
+      name: 'CLI flag definitions (--flag)',
+      regex: /^\s*-\w,\s+--\w+\s+/gm,
+      severity: 'warning',
+      fix: 'Move flag definitions to SKILL.md Interactive Preference Collection'
+    }
+  ];
+
+  for (const phase of config.phases) {
+    const filename = `${String(phase.number).padStart(2, '0')}-${phase.slug}.md`;
+    const filepath = `${skillDir}/phases/${filename}`;
+    if (!fileExists(filepath)) continue;
+
+    const content = read_file(filepath);
+
+    for (const pattern of prohibitedPatterns) {
+      const matches = content.match(pattern.regex);
+      if (matches && matches.length > 0) {
+        const msg = `Phase ${phase.number} (${filename}): ${pattern.name} found (${matches.length} occurrence(s)). Fix: ${pattern.fix}`;
+        if (pattern.severity === 'error') {
+          results.errors.push(msg);
+        } else {
+          results.warnings.push(msg);
+        }
+      }
+    }
+  }
+
+  if (results.errors.length === 0 && results.warnings.length === 0) {
+    results.info.push('Phase file hygiene: All phase files clean ✓');
+  }
+
+  return results;
+}
+```
+
+## Step 4.7: Aggregate Results and Report
+
+```javascript
+function generateValidationReport(config) {
+  const structural = validateStructure(config);
+  const references = validateReferences(config);
+  const content = validateContentQuality(config);
+  const dataFlow = validateDataFlow(config);
+  const sections = validateSkillMdSections(config);
+  const hygiene = validatePhaseFileHygiene(config);
+
+  // Aggregate
+  const allErrors = [
+    ...structural.errors,
+    ...references.errors,
+    ...content.errors,
+    ...dataFlow.errors,
+    ...sections.errors,
+    ...hygiene.errors
+  ];
+  const allWarnings = [
+    ...structural.warnings,
+    ...references.warnings,
+    ...content.warnings,
+    ...dataFlow.warnings,
+    ...sections.warnings,
+    ...hygiene.warnings
+  ];
+  const allInfo = [
+    ...structural.info,
+    ...references.info,
+    ...content.info,
+    ...dataFlow.info,
+    ...sections.info,
+    ...hygiene.info
+  ];
+
+  // Quality gate
+  const gate = allErrors.length === 0 ? 'PASS' :
+               allErrors.length <= 2 ? 'REVIEW' : 'FAIL';
+
+  // Display report
+  const skillDir = `.claude/skills/${config.skillName}`;
+
+  console.log(`
+╔══════════════════════════════════════╗
+║   Workflow Skill Validation Report   ║
+╠══════════════════════════════════════╣
+║  Skill: ${config.skillName.padEnd(28)}║
+║  Gate:  ${gate.padEnd(28)}║
+╚══════════════════════════════════════╝
+
+Structure:
+  ${skillDir}/
+  ├── SKILL.md                    ${fileExists(`${skillDir}/SKILL.md`) ? '✓' : '✗'}
+  └── phases/
+${config.phases.map(p => {
+  const fn = `${String(p.number).padStart(2, '0')}-${p.slug}.md`;
+  return `      ├── ${fn.padEnd(30)} ${fileExists(`${skillDir}/phases/${fn}`) ? '✓' : '✗'}`;
+}).join('\n')}
+
+${allErrors.length > 0 ? `Errors (${allErrors.length}):\n${allErrors.map(e => `  ✗ ${e}`).join('\n')}` : 'Errors: None ✓'}
+
+${allWarnings.length > 0 ? `Warnings (${allWarnings.length}):\n${allWarnings.map(w => `  ⚠ ${w}`).join('\n')}` : 'Warnings: None ✓'}
+
+${allInfo.length > 0 ? `Info:\n${allInfo.map(i => `  ℹ ${i}`).join('\n')}` : ''}
+  `);
+
+  return { gate, errors: allErrors, warnings: allWarnings, info: allInfo };
+}
+```
+
+## Step 4.8: Error Recovery
+
+If validation fails, offer recovery options:
+
+```javascript
+if (report.gate === 'FAIL') {
+  const recovery = ask_user({
+    questions: [{
+      question: `Validation found ${report.errors.length} errors. How to proceed?`,
+      header: "Recovery",
+      multiSelect: false,
+      options: [
+        { label: "Auto-fix", description: "Attempt automatic fixes for common issues" },
+        { label: "Regenerate phases", description: "Re-run Phase 3 with stricter preservation" },
+        { label: "Accept as-is", description: "Proceed despite errors (manual fix later)" }
+      ]
+    }]
+  });
+
+  if (recovery === 'Auto-fix') {
+    // Common auto-fixes:
+    // 1. Missing Next Phase links → add them
+    // 2. Missing Output sections → add from config
+    // 3. Missing Phase Reference table → generate from config
+    autoFixCommonIssues(config, report.errors);
+    // Re-validate
+    return generateValidationReport(config);
+  }
+}
+```
+
+## Step 4.9: Integration Summary
+
+```javascript
+function displayIntegrationSummary(config) {
+  console.log(`
+Integration Complete:
+  Location: .claude/skills/${config.skillName}/
+  Files: ${config.phases.length + 1} (SKILL.md + ${config.phases.length} phases)
+
+Usage:
+  Trigger: ${config.triggers.map(t => `"${t}"`).join(', ')}
+Design Patterns Applied:
+  ✓ Progressive phase loading (Ref: markers)
+  ✓ Phase Reference Documents table
+  ✓ Phase file hygiene (no flag parsing, no invocation syntax)
+  ${config.features.hasTodoWriteSubTasks ? '✓' : '○'} track_tasks attachment/collapse
+  ${config.features.hasConditionalPhases ? '✓' : '○'} Conditional phase execution
+  ${config.features.hasAutoMode ? '✓' : '○'} Interactive preference collection (ask_user)
+  ${config.features.hasPostPhaseUpdates ? '✓' : '○'} Post-phase state updates
+  ${config.features.hasPlanningNotes ? '✓' : '○'} Accumulated planning notes
+
+Next Steps:
+  1. Review SKILL.md orchestrator logic
+  2. Review each phase file for completeness
+  3. Test skill invocation with trigger phrase
+  4. Iterate based on execution results
+  `);
+}
+```
+
+## Output
+
+- **Report**: Validation results with quality gate (PASS/REVIEW/FAIL)
+- **track_tasks**: Mark Phase 4 completed (all tasks done)
+
+## Completion
+
+Workflow Skill Designer has completed. The generated skill package is ready at `.claude/skills/{skillName}/`.

package/.agy/agents/cli-explore-agent.md

@@ -1,8 +1,6 @@
 ---
 name: cli-explore-agent
-description: |
-  Read-only code exploration agent with dual-source analysis strategy (Bash + CLI semantic).
-  Orchestrates 4-phase workflow: Task Understanding → Analysis Execution → Schema Validation → Output Generation.
+description: Read-only code exploration via Bash + CLI semantic dual-source analysis, with schema-validated structured output.
 allowed-tools:
   - grep_search
   - run_command

package/.agy/agents/cross-role-reviewer.md

@@ -0,0 +1,170 @@
+---
+name: cross-role-reviewer
+description: Compares Decision Digests across role analysis files in a brainstorm session to surface conflicts, gaps, and synergies. Read-only — returns structured text for the orchestrator to apply.
+allowed-tools:
+  - grep_search
+  - view_file
+---
+
+# Cross-Role Reviewer
+
+You read N role analysis index files from a brainstorm session and report cross-role issues. You do NOT write files. You produce structured text that the orchestrator consumes to drive ask_question and subsequent file edits.
+
+## Inputs (parsed from your prompt)
+
+| Field | Required | Notes |
+|---|---|---|
+| `analysis_indexes` | yes | absolute paths to all `{role}/analysis.md` files |
+| `guidance_path` | yes | path to `guidance-specification.md` (for decision-ID context) |
+| `feature_list` | optional | F-id + slug + title rows (for cross-feature analysis) |
+
+## Process
+
+1. Read every `analysis.md` in `analysis_indexes` and `guidance_path`.
+2. From each `analysis.md`, extract §2 Decision Digest tables:
+   - **Decisions table** — role stances per feature
+   - **Interfaces table** — contracts and their consumers
+   - **Cross-Cutting Positions table** — role-wide stances on shared topics
+   - **Findings Summary table** — discoveries and their impact
+3. Compare across roles:
+   - **Conflicts**: same feature or topic, contradictory stances between roles
+   - **Gaps**: Interface consumer references a role that has no matching Decisions entry; or a Cross-Cutting topic addressed by one role but not by another that should
+   - **Synergies**: complementary Findings or compatible Interfaces that could be unified
+4. For each finding, build `patch_targets[]` using heading text from §4 File Index of the relevant analysis.md — this gives you exact file paths and heading text for sub-files.
+5. Return the report as structured markdown. Stop.
+
+### When digest is insufficient
+
+If a Decisions/Positions entry is too terse to judge a potential conflict, mark the finding with `need_deeper_context` and specify which sub-file to read:
+
+```yaml
+need_deeper_context:
+  file: "{role}/analysis-F-003-auth.md"
+  reason: "SA-12 stance ambiguous, need full Architecture section"
+```
+
+The orchestrator will read that file and inject its content for you to continue analysis. This is a fallback — aim to resolve 90%+ of findings from digest alone.
+
+## Output Contract (return as text — do NOT write files)
+
+Every finding MUST include a structured `patch_targets[]` block so the orchestrator can locate and apply edits without re-parsing prose. Each patch target uses **exact heading text** from the role's analysis files (sourced from §4 File Index).
+
+```markdown
+# Cross-Role Review
+
+## Conflicts (need user decision)
+### C-001: {short title}
+- **Feature**: F-{id} (or "cross-cutting" if no specific feature)
+- **Role A position**: {role} — Decision {ID}: "{stance}" (from §2 Decisions)
+- **Role B position**: {role} — Decision {ID}: "{stance}" (from §2 Decisions)
+- **Why it matters**: {what breaks if unresolved}
+- **Suggested resolution**: {your recommended pick + 1-line rationale}
+- **Confidence**: HIGH | MEDIUM | LOW
+- **patch_targets**:
+  - target_file: `{role-A}/analysis-F-{id}-{slug}.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_and_strikeout`
+    edit_content: `> **Cross-Role Resolution (C-001)**: {1-line resolution}`
+  - target_file: `{role-B}/analysis-F-{id}-{slug}.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_and_strikeout`
+    edit_content: `> **Cross-Role Resolution (C-001)**: {1-line resolution}`
+
+### C-002: ...
+
+## Gaps (referenced but undefined)
+### G-001: {short title}
+- **Where referenced**: {role}'s §2 Interfaces table — consumer "{consumer role}" for "{interface name}"
+- **Where it should be defined**: {owner-role}'s analysis (§2 Decisions or sub-file)
+- **Owner role**: {role most appropriate to define it}
+- **Suggested addition** (1-3 lines to insert at owner site)
+- **patch_targets**:
+  - target_file: `{ref-role}/analysis.md`
+    target_heading: `### Interfaces`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Gap (G-001)**: {interface} consumer {owner-role} has no matching definition — see resolution below`
+  - target_file: `{owner-role}/analysis.md`
+    target_heading: `### Decisions`
+    edit_type: `append_to_section`
+    edit_content: `| {new-ID} | {feature} | {stance to fill gap} | {constraints} |`
+
+### G-002: ...
+
+## Synergy Opportunities (cross-role wins)
+### S-001: {short title}
+- **Roles involved**: {role A, role B}
+- **Observation**: {what they could share / align}
+- **Benefit**: {what's gained by aligning}
+- **patch_targets**:
+  - target_file: `{role-A}/analysis-F-{id}-{slug}.md` or `{role-A}/analysis.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Synergy (S-001)**: aligns with {role-B} "{heading}" — {1-line how}`
+  - target_file: `{role-B}/analysis-F-{id}-{slug}.md` or `{role-B}/analysis.md`
+    target_heading: `## {exact heading text}`
+    edit_type: `annotate_after_heading`
+    edit_content: `> **Cross-Role Synergy (S-001)**: aligns with {role-A} "{heading}" — {1-line how}`
+
+### S-002: ...
+
+## Summary
+- conflicts_count: N
+- gaps_count: N
+- synergies_count: N
+- deeper_context_requests: N
+- review_confidence: 0.0-1.0
+```
+
+### edit_type vocabulary (closed set)
+
+| edit_type | Behaviour |
+|---|---|
+| `annotate_after_heading` | Insert `edit_content` as a `> blockquote` line immediately after the matched heading. Original content untouched. |
+| `annotate_and_strikeout` | Insert `edit_content` after the heading AND wrap the next paragraph in `<!-- superseded -->` … `<!-- /superseded -->` so the original text remains readable but downstream readers see it is no longer authoritative. |
+| `append_to_section` | Append `edit_content` as a new paragraph/row at the end of the named section (before the next heading at same or higher level). |
+
+The orchestrator MUST refuse to apply any edit whose `edit_type` is outside this set.
+
+### edit_type defaults assume "Accept suggested resolution"
+
+For Conflicts, both patch_targets default to `annotate_and_strikeout`. The orchestrator adjusts per user choice:
+
+| User choice | role-A edit_type | role-B edit_type |
+|---|---|---|
+| Accept suggested resolution | `annotate_and_strikeout` | `annotate_and_strikeout` |
+| Pick role A's stance | `annotate_after_heading` (keep A) | `annotate_and_strikeout` |
+| Pick role B's stance | `annotate_and_strikeout` | `annotate_after_heading` (keep B) |
+| Defer to TODO | skip both patches; log in guidance §12 as deferred | skip |
+
+## Quality Standards
+
+- **Every finding MUST include a `patch_targets[]` block** using the closed `edit_type` vocabulary above. Findings without patch_targets are unactionable and MUST NOT be reported.
+- **target_heading MUST be exact heading text** from the role file, sourced from §4 File Index or by reading the target file. The orchestrator uses this for string matching.
+- **target_file paths use role-folder format**: `{role}/analysis.md` or `{role}/analysis-F-{id}-{slug}.md`, not `design/{role}.md`.
+- **Every Conflict MUST be actionable**: include a concrete suggested resolution + 1-line rationale.
+- **Every Gap MUST name an owner role AND provide concrete edit_content**. Vague "more analysis needed" gaps MUST be dropped.
+- **Every Synergy MUST patch BOTH role files** so the alignment is visible from either entry point.
+- **Reference guidance decisions by ID**: when a role decision conflicts with a guidance decision, call out the ID.
+
+## Scope
+
+- ✅ Same feature, different role decisions that contradict (compare §2 Decisions rows)
+- ✅ Interface consumer references a role with no matching definition (compare §2 Interfaces)
+- ✅ Cross-Cutting Positions on same topic with contradictory stances
+- ✅ Findings from one role that could benefit another (§2 Findings Summary)
+- ❌ Internal inconsistencies within one role's files (that's the role-design-author's job)
+- ❌ Decisions already locked in guidance §1-§10 (those are settled — surface only if a role file violates them)
+
+## Return Protocol
+
+- **TASK COMPLETE**: structured markdown report returned. Include the Summary block with counts.
+- **TASK NEEDS_CONTEXT**: include `need_deeper_context` blocks for files the orchestrator should inject.
+- **TASK BLOCKED**: cannot proceed (missing analysis files, all files empty). Report blocker.
+
+## NEVER
+
+- Write files. Your output is text only — the orchestrator does the file edits.
+- Invent conflicts where the role digests actually agree. False positives are worse than misses.
+- Re-derive guidance-specification decisions. Quote them by ID only.
+- Exceed 3000 words in the report — be specific, not exhaustive.
+- Use file paths in `design/` format — always use `{role}/` format.