bmad-module-skill-forge 0.5.0 → 0.7.0

package/src/workflows/verify-stack/steps-c/step-03-integrations.md

@@ -0,0 +1,195 @@
+---
+name: 'step-03-integrations'
+description: 'Pass 2 — cross-reference API surfaces between library pairs based on integration claims in the architecture document'
+
+nextStepFile: './step-04-requirements.md'
+integrationRulesData: '../data/integration-verification-rules.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 3: Integration Verification
+
+## STEP GOAL:
+
+Cross-reference API surfaces between library pairs that the architecture document claims work together. For each integration pair, verify language compatibility, protocol alignment, type compatibility, and documentation cross-references. Produce an evidence-backed verdict for each integration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a stack verification analyst performing integration feasibility analysis
+- ✅ Every verdict must cite evidence from the actual skill content — no speculation
+- ✅ Apply the verification protocol strictly — do not skip compatibility checks
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on integration pair verification using skill API surfaces
+- 🚫 FORBIDDEN to evaluate requirements coverage — that is Step 04
+- 🚫 FORBIDDEN to parse Mermaid diagrams — use prose-based co-mention analysis only
+- 💬 Every verdict MUST include evidence citations from the skills
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract integration claims from architecture document prose
+- 💾 Load skill API surfaces and cross-reference each integration pair
+- 📖 Append Integration Verdicts section to {outputFile}
+- 🚫 Only integration analysis — no requirements checking, no synthesis
+
+## CONTEXT BOUNDARIES:
+
+- Available: Architecture document content, skill SKILL.md and metadata.json files, integration verification rules
+- Focus: Pairwise integration compatibility between skills
+- Limits: Only verify pairs explicitly claimed in the architecture document — do not invent integration relationships
+- Dependencies: Step 01 (skill inventory), Step 02 (coverage matrix — only verify skills that exist)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Load Integration Verification Rules
+
+Load `{integrationRulesData}` for the cross-reference verification protocol.
+
+Extract: verification checks (language boundary, protocol compatibility, type compatibility, documentation cross-reference), verdict criteria, and evidence requirements.
+
+### 2. Extract Integration Claims
+
+Parse the architecture document for statements describing two or more technologies working together.
+
+**Detection method — prose-based co-mention analysis:**
+- Identify sentences or paragraphs where two or more technology names appear together
+- Look for integration verbs: "connects to", "communicates with", "wraps", "extends", "consumes", "produces", "bridges", "integrates with", "sits between"
+- Look for data flow descriptions: "{A} sends data to {B}", "{A} results are consumed by {B}"
+- Look for layer boundary descriptions: "{A} at the API layer connects to {B} at the data layer"
+
+**CRITICAL:** Do NOT parse Mermaid diagram syntax. Use only prose text for co-mention detection.
+
+**Build integration pairs list:**
+- Each pair: `{library_a, library_b, architectural_context}`
+- `architectural_context`: the quoted text or paraphrased description of their relationship
+
+**Filter:** Only include pairs where BOTH libraries have a corresponding skill (Covered in Step 02). Skip pairs involving Missing skills — they cannot be verified.
+
+### 3. Load Skill API Surfaces
+
+For each library in an integration pair, load the skill artifacts:
+
+**From SKILL.md, extract:**
+- Exported functions and their signatures
+- Exported types, interfaces, and classes
+- Protocol indicators (HTTP, gRPC, WebSocket, message queue, file I/O, IPC)
+- Data format indicators (JSON, protobuf, CSV, binary, streaming)
+
+**From metadata.json, extract:**
+- `language` — primary programming language
+- `exports` — export names array (populated for individual skills; empty for stack skills)
+- `stats.exports_documented` — export count
+- `confidence_tier` — extraction confidence level
+
+Store loaded API surfaces for cross-referencing.
+
+### 4. Cross-Reference Each Integration Pair
+
+For each integration pair `{library_a, library_b}`, apply the verification protocol from `{integrationRulesData}`:
+
+**Check 1 — Language Boundary:**
+- Same language → compatible
+- Different languages → check for FFI, IPC, or network protocol bridge
+- If no bridge mechanism documented → flag as risk
+
+**Check 2 — Protocol Compatibility:**
+- Both use same protocol (e.g., both HTTP) → compatible
+- Complementary protocols (e.g., HTTP client + HTTP server) → compatible
+- Incompatible protocols with no adapter → flag as risk
+
+**Check 3 — Type Compatibility:**
+- Shared types or compatible serialization formats → compatible
+- Incompatible type systems with no conversion layer → flag as risk
+
+**Check 4 — Documentation Cross-Reference:**
+- Skill A mentions skill B's library (or vice versa) → strong evidence
+- Neither skill mentions the other → weak evidence (plausible but unverified)
+
+**Assign verdict per pair:**
+- **Verified** — all checks pass with evidence from both skills
+- **Plausible** — checks pass but evidence is indirect or incomplete
+- **Risky** — one or more checks flag compatibility concerns
+- **Blocked** — fundamental incompatibility detected (language barrier with no bridge, incompatible protocols)
+
+**Each verdict MUST include:**
+- Which checks passed and which flagged
+- Evidence citations: specific exports, types, or protocol references from the skills
+
+### 5. Display Integration Results
+
+"**Pass 2: Integration Verification**
+
+| Library A | Library B | Context | Verdict | Evidence |
+|-----------|-----------|---------|---------|----------|
+| {lib_a} | {lib_b} | {brief context} | {Verified/Plausible/Risky/Blocked} | {key evidence} |
+
+**Summary:** {verified_count} Verified, {plausible_count} Plausible, {risky_count} Risky, {blocked_count} Blocked
+
+{IF zero integration pairs found:}
+**No integration claims detected in the architecture document prose.** Ensure your architecture document describes relationships between technologies in text form (not exclusively in Mermaid diagrams). Coverage-only analysis was performed.
+
+{IF any Risky:}
+**Risky Integrations — Recommendations:**
+{For each risky pair:}
+- `{lib_a}` ↔ `{lib_b}`: {specific concern}. **Recommendation:** {prescriptive action}
+
+{IF any Blocked:}
+**Blocked Integrations — Action Required:**
+{For each blocked pair:}
+- `{lib_a}` ↔ `{lib_b}`: {fundamental incompatibility}. **Recommendation:** {prescriptive action}"
+
+### 6. Append to Report
+
+Write the **Integration Verdicts** section to `{outputFile}`:
+- Include the full integration verdicts table with evidence
+- Include recommendations for Risky and Blocked pairs
+- Update frontmatter: append `'step-03-integrations'` to `stepsCompleted`
+- Set `integrations_verified`, `integrations_plausible`, `integrations_risky`, `integrations_blocked` counts
+
+### 7. Auto-Proceed to Next Step
+
+**Early halt guard:** If ALL integration pairs are Blocked, present: "**All integrations are Blocked** — fundamental incompatibilities detected across all library pairs. Remaining analysis will produce limited value. **[X] Halt workflow (recommended)** | **[C] Continue anyway**" — wait for user input. If X: halt with: "**Workflow halted — all integrations blocked.** Integration Verdicts saved to `{outputFile}`. Run **[VS]** after applying architectural changes. **Blocked integrations:** {list each blocked pair with reason}." If C: continue.
+
+{IF NOT halted (user selected C, or early halt guard did not trigger):}
+
+"**Proceeding to requirements verification...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Integration rules loaded from {integrationRulesData}
+- Integration claims extracted from architecture document prose (not Mermaid diagrams)
+- Skill API surfaces loaded for each library in integration pairs
+- All four verification checks applied to each pair
+- Every verdict includes evidence citations from actual skill content
+- Recommendations provided for every Risky and Blocked integration
+- Integration Verdicts section appended to {outputFile}
+- Auto-proceeded to step 04
+
+### ❌ SYSTEM FAILURE:
+
+- Parsing Mermaid diagrams instead of using prose-based co-mention analysis
+- Verdicts without evidence citations from actual skills
+- Inventing integration relationships not described in the architecture document
+- Skipping any of the four verification checks
+- Evaluating requirements coverage (that is Step 04)
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/verify-stack/steps-c/step-04-requirements.md

@@ -0,0 +1,168 @@
+---
+name: 'step-04-requirements'
+description: 'Pass 3 (OPTIONAL) — if PRD/vision document provided, verify the stack covers stated requirements'
+
+nextStepFile: './step-05-synthesize.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 4: Requirements Coverage
+
+## STEP GOAL:
+
+If a PRD or vision document was provided in Step 01, verify that the combined capabilities of the generated skills address each stated requirement. If no PRD was provided, skip this pass and auto-proceed. Produce a requirements coverage table with Fulfilled, Partially Fulfilled, or Not Addressed verdicts.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a stack verification analyst assessing requirements coverage
+- ✅ Every verdict must reason from actual skill capabilities, not assumptions
+- ✅ "Not Addressed" is a valid and important finding — do not force-fit skills to requirements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on requirements-to-skills coverage assessment
+- 🚫 FORBIDDEN to re-analyze integrations — that was Step 03
+- 🚫 FORBIDDEN to synthesize or produce overall verdicts — that is Step 05
+- 💬 If no PRD was provided, skip immediately with a clear message
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract requirements from PRD/vision document and assess skill coverage
+- 💾 Append Requirements Coverage section to {outputFile}
+- 📖 Auto-proceed to next step after completion or skip
+- 🚫 Only requirements coverage — no synthesis, no overall verdict
+
+## CONTEXT BOUNDARIES:
+
+- Available: PRD/vision document (if provided), skill SKILL.md files, metadata.json files
+- Focus: Mapping requirements to skill capabilities
+- Limits: Do not evaluate skill quality — only whether capabilities match requirements
+- Dependencies: Step 01 (PRD availability flag, skill inventory)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check PRD Availability
+
+**Check `prd_available` from workflow state (set in Step 01). If `prd_available` is false (no PRD/vision document was provided):**
+
+"**Pass 3: Requirements Coverage — Skipped**
+
+No PRD or vision document was provided. Requirements coverage analysis requires a document describing project capabilities and constraints.
+
+To include this pass, re-run **[VS]** with a PRD or vision document path.
+
+**Proceeding to synthesis...**"
+
+Update {outputFile} frontmatter: append `'step-04-requirements'` to `stepsCompleted`, set `requirements_pass: "skipped"`.
+
+Load, read the full file and then execute `{nextStepFile}`. **STOP HERE — do not execute sections 2-6.**
+
+**If PRD/vision document was provided:** Continue to section 2.
+
+### 2. Extract Requirements
+
+Parse the PRD/vision document for capability requirements.
+
+**Look for:**
+- **Feature descriptions** — explicit capabilities the product must have
+- **Technical requirements** — performance targets, scalability needs, platform support
+- **Non-functional requirements** — offline-first, real-time sync, multi-language support, accessibility, security constraints
+- **Integration requirements** — third-party service dependencies, API contracts
+- **Infrastructure requirements** — deployment targets, CI/CD needs, monitoring
+
+**Build a requirements list** with each entry containing:
+- `requirement_id` — sequential identifier (R1, R2, R3...)
+- `requirement_text` — the stated requirement
+- `category` — feature, technical, non-functional, integration, or infrastructure
+- `source_section` — the PRD section where it was found
+
+### 3. Assess Stack Coverage
+
+For each requirement, evaluate whether the combined capabilities of the generated skills address it.
+
+**Assessment method:**
+- Read each skill's SKILL.md exports, description, and capabilities sections
+- Check if skill exports provide functions, types, or patterns relevant to the requirement
+- Consider combinations of multiple skills that together address a requirement
+- For non-functional requirements, check if skills document relevant configuration or patterns
+
+**Assign verdict per requirement:**
+- **Fulfilled** — one or more skills clearly provide the needed capability, with specific exports or patterns identified
+- **Partially Fulfilled** — skills provide related capability but gaps remain (specify what is covered and what is not)
+- **Not Addressed** — no skill in the stack provides capability relevant to this requirement
+
+**Each verdict MUST include:**
+- Which skills contribute (if any)
+- Specific exports or capabilities from those skills that are relevant
+- For Partially Fulfilled: what gap remains
+
+### 4. Display Requirements Results
+
+"**Pass 3: Requirements Coverage**
+
+| ID | Requirement | Category | Verdict | Contributing Skills |
+|----|-------------|----------|---------|-------------------|
+| {id} | {requirement_text} | {category} | {Fulfilled/Partially Fulfilled/Not Addressed} | {skill_names or '—'} |
+
+**Coverage: {fulfilled_count} Fulfilled, {partial_count} Partially Fulfilled, {not_addressed_count} Not Addressed**
+
+{IF any Not Addressed:}
+**Unaddressed Requirements — Recommendations:**
+{For each not addressed requirement:}
+- **{id}:** {requirement_text} → Evaluate `{category}` libraries that provide this capability, generate a skill with **[CS]** or **[QS]**, then re-run **[VS]**
+
+{IF any Partially Fulfilled:}
+**Partial Coverage — Details:**
+{For each partially fulfilled requirement:}
+- **{id}:** Covered by `{skill_names}` — **Gap:** {what remains unaddressed}"
+
+### 5. Append to Report
+
+Write the **Requirements Coverage** section to `{outputFile}`:
+- Include the full requirements coverage table
+- Include recommendations for Not Addressed and Partially Fulfilled items
+- Update frontmatter: append `'step-04-requirements'` to `stepsCompleted`
+- Set `requirements_pass: "completed"`
+- Set `requirements_fulfilled`, `requirements_partial`, `requirements_not_addressed` counts
+
+### 6. Auto-Proceed to Next Step
+
+"**Proceeding to synthesis...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- PRD availability checked first — skipped cleanly if not provided
+- All requirements extracted from PRD with source section citations
+- Each requirement assessed against actual skill capabilities (exports, descriptions)
+- Verdicts include contributing skill names and specific capabilities
+- Not Addressed items have actionable recommendations
+- Requirements Coverage section appended to {outputFile}
+- Auto-proceeded to step 05
+
+### ❌ SYSTEM FAILURE:
+
+- Fabricating requirements not stated in the PRD document
+- Force-fitting skills to requirements they do not address
+- Verdicts without evidence from actual skill content
+- Not executing the skip path when no PRD was provided
+- Producing synthesis or overall verdicts (that is Step 05)
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/verify-stack/steps-c/step-05-synthesize.md

@@ -0,0 +1,191 @@
+---
+name: 'step-05-synthesize'
+description: 'Produce overall feasibility verdict, prescriptive recommendations, and diff from previous run'
+
+nextStepFile: './step-06-report.md'
+outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+---
+
+# Step 5: Synthesize Verdict
+
+## STEP GOAL:
+
+Calculate the overall feasibility verdict based on all three analysis passes, generate prescriptive recommendations for every non-verified finding, check for a previous feasibility report to produce a delta, and compile the synthesis section of the report.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a stack verification analyst delivering the final synthesis
+- ✅ The overall verdict must follow the decision logic exactly — no subjectivity
+- ✅ Every recommendation must be specific and actionable — not vague advice
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on synthesizing findings from Steps 02-04 into a verdict
+- 🚫 FORBIDDEN to discover new findings or re-analyze skills
+- 🚫 FORBIDDEN to present the final report to the user — that is Step 06
+- 💬 Recommendations must name specific tools, libraries, or actions
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Apply verdict decision logic to produce FEASIBLE / CONDITIONALLY FEASIBLE / NOT FEASIBLE
+- 💾 Append Synthesis & Recommendations section to {outputFile}
+- 📖 Check for previous report and generate delta if found
+- 🚫 Only synthesis — no new analysis, no final presentation
+
+## CONTEXT BOUNDARIES:
+
+- Available: Coverage matrix (Step 02), integration verdicts (Step 03), requirements coverage (Step 04 if applicable)
+- Focus: Verdict calculation, recommendation generation, delta comparison
+- Limits: Do not present the full report — that is Step 06
+- Dependencies: Steps 02-03 must be complete; Step 04 completed or skipped
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Calculate Overall Verdict
+
+Apply the following decision logic using findings from all completed passes:
+
+**Evaluate in order — the first matching condition wins. Do not continue once a verdict is determined.**
+
+**NOT FEASIBLE (evaluate first):**
+- Any integration is **Blocked** → overall verdict is NOT FEASIBLE
+- Rationale: a blocked integration represents a fundamental architectural incompatibility. Also note in the rationale any co-occurring Missing skills or Risky integrations so the user understands the full set of problems
+
+**CONDITIONALLY FEASIBLE (evaluate second):**
+If ANY of the following apply, the verdict is CONDITIONALLY FEASIBLE. Include ALL matching conditions in the rationale:
+- Any technology is **Missing** from coverage (no skill exists)
+- Any integration is **Risky** (but none Blocked)
+- Requirements have any **Not Addressed** items
+- Requirements have any **Partially Fulfilled** items
+- Rationale: the stack can work but has gaps, risks, or unverified assumptions that must be addressed
+
+**FEASIBLE (evaluate last):**
+- Coverage is 100% (no Missing skills) AND all integrations are Verified or Plausible AND requirements are all Fulfilled (or requirements pass was skipped) AND no Blocked or Risky integrations → overall verdict is FEASIBLE
+- Rationale: {IF requirements pass completed:} the stack can support the architecture as described — all requirements fully fulfilled. {IF requirements pass was skipped:} the stack can support the architecture as described — requirements were not evaluated (no PRD provided)
+
+**Post-verdict: Zero integration pairs guard (apply after ANY verdict):**
+If zero integration pairs were extracted (all four integration counts are 0) AND the architecture document references 2+ technologies:
+- If the verdict was FEASIBLE, override to CONDITIONALLY FEASIBLE
+- Regardless of verdict, append this note to the rationale: "No integration claims were found in the architecture document prose. Manual review recommended to confirm that technology relationships are not documented exclusively in diagrams or implied without explicit co-mention."
+
+Store the verdict for use in the report.
+
+### 2. Generate Prescriptive Recommendations
+
+For each non-verified finding across all passes, generate an actionable next step:
+
+**Missing skill (from Step 02):**
+- "Run **[CS] Create Skill** or **[QS] Quick Skill** for `{library_name}`, then re-run **[VS]** to verify coverage."
+
+**Risky integration (from Step 03):**
+- If protocol mismatch → "Consider adding a bridge layer between `{lib_a}` and `{lib_b}` (e.g., HTTP adapter, message queue). Document the bridge in the architecture."
+- If type incompatibility → "Add a serialization/conversion layer between `{lib_a}` and `{lib_b}` to resolve the type mismatch identified in their API surfaces."
+- If weak evidence → "Add cross-references between `{lib_a}` and `{lib_b}` skills by re-running **[CS]** with integration context."
+
+**Blocked integration (from Step 03):**
+- If language barrier → "Replace `{lib_a}` with a `{lib_b_language}`-compatible alternative, or introduce an IPC/FFI bridge. Redesign the integration path in the architecture document."
+- If fundamental incompatibility → "Replace `{blocked_lib}` with an alternative that is compatible with `{other_lib}` in the same domain, or redesign the integration path in the architecture document."
+
+**Not Addressed requirement (from Step 04):**
+- "No library in the stack covers `{requirement}`. Evaluate `{category}` libraries that provide this capability, generate a skill, then re-run **[VS]**."
+
+**Partially Fulfilled requirement (from Step 04):**
+- "Gap in `{requirement}`: {what_is_missing}. Consider extending `{contributing_skill}` or adding a dedicated library."
+
+**Zero integration pairs (from Step 03):**
+- If zero integration pairs were found AND the architecture references 2+ technologies: "No integration claims were found in the architecture document prose. Add explicit prose descriptions of how your technologies interact (not only in diagrams), then re-run **[VS]** to verify integrations."
+
+### 3. Check for Previous Report
+
+Check if a `previous_report` path was recorded in the current report's frontmatter. Since the current workflow run overwrites the report starting in Step 01, the delta feature requires the user to have saved a copy before re-running [VS].
+
+**Note:** The delta feature is only available when the user has manually backed up a prior report and provided the path. To enable delta comparisons, instruct the user to copy their feasibility report (e.g., `feasibility-report-{project_name}-v1.md`) before re-running [VS], then provide the backup path when prompted in Step 01.
+
+**If a previous report is found:**
+- Load its verdict, coverage percentage, and integration verdicts
+- Generate a delta comparison:
+  - **Improved items:** findings that were Risky/Blocked/Missing and are now Verified/Covered
+  - **Regressed items:** findings that were Verified/Covered and are now Risky/Blocked/Missing
+  - **New items:** findings not present in the previous report
+  - **Unchanged items:** count of findings with the same verdict
+
+**If no previous report found:**
+- Note: "First verification run — no delta available."
+
+### 4. Compile Synthesis Section
+
+Assemble the following for the report:
+
+**Overall verdict** with rationale citing the decision logic.
+
+**Recommendation list** ordered by priority (count total recommendations as `recommendation_count` — persist this count to `{outputFile}` frontmatter for use in step-06):
+1. Blocked integrations (if any)
+2. Missing skills
+3. Risky integrations
+4. Not Addressed requirements
+5. Partially Fulfilled requirements
+
+**Delta from previous run** (if applicable):
+- Improved, regressed, new, unchanged counts
+- Specific items that changed
+
+**Suggested next workflow:**
+- FEASIBLE → "Proceed to **[RA] Refine Architecture** to produce an implementation-ready architecture, then **[SS]** to compose your stack skill, then **[TS]** to test and **[EX]** to export."
+- CONDITIONALLY FEASIBLE → "Address the {recommendation_count} recommendations above, then re-run **[VS]**. Once all clear, proceed to **[RA]**."
+- NOT FEASIBLE → "Critical blockers must be resolved before proceeding. Apply the recommendations above and re-run **[VS]**."
+
+### 5. Append to Report
+
+Write the **Synthesis & Recommendations** section to `{outputFile}`:
+- Include overall verdict with rationale
+- Include prioritized recommendation list
+- Include delta from previous run (if applicable)
+- Include suggested next workflow
+- **Replace the body placeholder** in the `## Overall Verdict` section: replace `{FEASIBLE / CONDITIONALLY FEASIBLE / NOT FEASIBLE}` and `{1-2 sentence summary}` with the actual calculated verdict and rationale text
+- Update frontmatter: append `'step-05-synthesize'` to `stepsCompleted`
+- Set `overall_verdict` to the calculated verdict
+- Set `recommendation_count` to the total number of recommendations
+- If delta was computed (section 3), set `delta_improved`, `delta_regressed`, `delta_new`, `delta_unchanged` in frontmatter to the respective counts
+- Verify that `integrations_verified`, `integrations_plausible`, `integrations_risky`, `integrations_blocked` in frontmatter match the counts from Step 03 (these were set in Step 03). If a discrepancy is found, overwrite the frontmatter counts with the values from Step 03 — the report file is the system of record
+
+### 6. Auto-Proceed to Next Step
+
+"**Proceeding to final report presentation...**"
+
+Load, read the full file and then execute `{nextStepFile}`.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Overall verdict calculated using the exact decision logic (not subjective judgment)
+- Every non-verified finding has a specific, actionable recommendation
+- Recommendations name concrete tools ([CS], [QS], [VS], [RA]) and specific libraries
+- Previous report delta generated if applicable
+- Synthesis section appended to {outputFile} with verdict, recommendations, and next workflow
+- Frontmatter updated with overall_verdict and metric counts
+- Auto-proceeded to step 06
+
+### ❌ SYSTEM FAILURE:
+
+- Subjective or vague overall verdict not following the decision logic
+- Recommendations without specific actions ("improve the integration")
+- Not checking for previous report
+- Discovering new findings or re-analyzing skills
+- Presenting the full report to the user (that is Step 06)
+- Hardcoded paths instead of frontmatter variables
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.