bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/skf-verify-stack/references/integration-verification-rules.md

@@ -0,0 +1,78 @@
+# Integration Verification Rules
+
+## Purpose
+
+Rules for cross-referencing API surfaces between two skills to determine integration feasibility.
+
+---
+
+## Verdict Definitions
+
+Token set is defined canonically in `src/shared/references/feasibility-report-schema.md` — the table below restates the same set with this skill's evidence obligations. Tokens are case-sensitive (`Verified`, `Plausible`, `Risky`, `Blocked`); emitting any other token is a schema violation.
+
+| Verdict       | Meaning                                                                                        | Required Evidence                                                                                                                                                                                                                                                   |
+|---------------|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Verified**  | APIs demonstrably connect AND docs cross-reference each other                                  | Check 1 (language) passes with declared evidence; Check 3 (types) passes from cited `exports` signatures; **Check 4 (docs cross-reference) MUST pass with a literal substring/name citation** — without Check 4 evidence, cap at `Plausible`. Check 2 is best-effort only and cannot by itself promote to `Verified`. |
+| **Plausible** | Checks pass but rely on inferred or indirect evidence                                          | Language + type checks pass; Check 2 uses inferred `protocols_inferred`/`data_formats_inferred` (prose scan); Check 4 is weak or missing (no literal cross-reference). This is the mandatory cap whenever Check 4 does not surface a literal citation.             |
+| **Risky**     | Type mismatch, protocol gap, or language boundary requiring a bridge                           | A clear gap exists (e.g., TypeScript↔Rust FFI needed) but a workaround is architecturally feasible — a named workaround MUST be cited in the recommendation                                                                                                        |
+| **Blocked**   | Fundamental incompatibility — no feasible integration path even with a bridge or adapter layer | The two libraries cannot exchange data in any documented way; requires replacing one of the libraries                                                                                                                                                              |
+
+**Promotion rule:** `Verified` requires Check 4 evidence. If Checks 1 and 3 pass but Check 4 fails (no literal substring/name citation from either skill's SKILL.md), the verdict is capped at `Plausible`. This rule is enforced by step-03 §4 and is the producer obligation declared in the shared schema.
+
+---
+
+## Cross-Reference Protocol
+
+For each integration pair (Library A ↔ Library B):
+
+### 1. Language Boundary Check
+
+| A Language          | B Language                             | Assessment                                                                       |
+|---------------------|----------------------------------------|----------------------------------------------------------------------------------|
+| Same language       | Same language                          | No boundary — direct API calls possible                                          |
+| TypeScript ↔ Rust   | Requires FFI, IPC, or WebSocket bridge | Check if a bridge library exists in the stack (e.g., Tauri provides JS↔Rust IPC) |
+| TypeScript ↔ Python | Requires REST/gRPC/WebSocket bridge    | Typically not direct                                                             |
+| Any ↔ C/C++         | FFI available in most languages        | Check for bindings                                                               |
+
+### 2. Protocol Compatibility Check
+
+| A Protocol                | B Protocol        | Assessment                                                  |
+|---------------------------|-------------------|-------------------------------------------------------------|
+| In-process (same runtime) | In-process        | Direct — function calls                                     |
+| HTTP/REST                 | HTTP/REST         | Network bridge — compatible if API endpoints match          |
+| WebSocket                 | WebSocket         | Real-time bridge — check message format compatibility       |
+| Shared filesystem         | Shared filesystem | Async — check format compatibility                          |
+| Embedded database         | Embedded database | May conflict on lock files — check for multi-writer support |
+
+### 3. Type Compatibility Check
+
+- Extract the primary data types each library produces/consumes from the skill's export list
+- Check: does Library A export a type that Library B accepts as input?
+- Common patterns: JSON serialization (universal bridge), binary formats (check codec), shared schemas (strong compatibility)
+
+### 4. Documentation Cross-Reference (required for `Verified`)
+
+- Search Skill A's SKILL.md for a literal substring/name citation of Library B
+- Search Skill B's SKILL.md for the reciprocal citation
+- Accept literal names or aliases declared in that skill's metadata; do NOT accept paraphrase or fuzzy matches
+- A pass requires at least one literal citation in at least one direction; the exact substring and location MUST be recorded in the evidence block
+- If neither skill literally cites the other, Check 4 FAILS and the per-pair verdict MUST cap at `Plausible` (not `Verified`)
+
+---
+
+## Verdict Evidence Format
+
+Each verdict MUST include:
+
+```
+**{Library A} ↔ {Library B}: {VERDICT}**
+
+Evidence:
+- A exports: `{function_name}({params}) → {return_type}` [from skill: {skill_name}]
+- B accepts: `{function_name}({params})` [from skill: {skill_name}]
+- Compatibility: {explanation}
+- Language boundary: {same | bridge required via {mechanism}}
+
+{If RISKY or BLOCKED:}
+Recommendation: {actionable next step}
+```

package/src/skf-verify-stack/steps-c/step-01-init.md

@@ -0,0 +1,178 @@
+---
+nextStepFile: './step-02-coverage.md'
+reportTemplate: 'assets/feasibility-report-template.md'
+feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
+atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
+---
+
+# Step 1: Initialize Verification
+
+## STEP GOAL:
+
+Load all generated skills from the skills output folder, accept the architecture document path (required) and optional PRD/vision document path from the user, validate that all inputs exist and are readable, create the feasibility report document, and present an initialization summary before auto-proceeding.
+
+## Rules
+
+- Focus only on loading inputs, scanning skills, and creating the report skeleton — do not perform analysis
+- Auto-proceed — halts only on validation errors
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Accept Input Documents
+
+"**Verify Stack — Feasibility Analysis**
+
+Please provide the following:
+1. **Architecture document path** (REQUIRED) — your project's architecture doc
+2. **PRD or vision document path** (OPTIONAL) — for requirements coverage analysis
+3. **Previous feasibility report path** (OPTIONAL) — for delta comparison with a prior run (provide a backup copy)"
+
+Wait for user input. **GATE [default: use args]** — If `{headless_mode}` and architecture doc path was provided as argument: use that path and auto-proceed, log: "headless: using provided architecture path".
+
+**Validate architecture document:**
+- Confirm the file exists and is readable
+- If missing or unreadable → "Architecture document not found at `{path}`. Provide a valid path."
+- HALT until a valid architecture document is provided
+
+**Validate PRD document (if provided):**
+- Confirm the file exists and is readable
+- If missing → "PRD document not found at `{path}`. Proceeding without PRD — requirements pass will be skipped."
+- Store PRD availability as `prdAvailable: true|false`
+
+**Validate previous report (if provided):**
+- Confirm the file exists and is readable
+- **Collision check:** Compare both the provided path and `{outputFile}` via `(st_dev, st_ino)` tuples obtained from `stat(2)` on each path (do not rely on absolute-path string equality — symlinks, bind mounts, and case-insensitive filesystems can defeat string comparison; the `(st_dev, st_ino)` comparison is the canonical kernel-level equivalent of `os.path.realpath`-based equality and is strictly stronger because it also catches hardlinks). If `{outputFile}` does not yet exist, resolve its parent via `realpath`, stat that directory, and combine `(st_dev, parent_ino, basename)` for comparison. If the two paths resolve to the same inode, warn: "The previous report path points to the same inode as the new report. This file will be overwritten during this run. Provide a path to a backup copy, or leave empty to skip delta comparison." HALT until resolved.
+- If missing → "Previous report not found at `{path}`. Proceeding without delta comparison."
+- Store as `previousReport: {path}` (or empty string if not provided)
+
+### 2. Scan Skills Folder
+
+**Pre-flight — skills folder existence:**
+- If `{skills_output_folder}` does not exist on disk: HALT with "**Cannot proceed.** `{skills_output_folder}` does not exist — run **[SF] Setup Forge** to initialize the forge, then generate skills with [CS] or [QS]."
+- If `{skills_output_folder}` exists but is empty (no subdirectories at all): HALT with "**Cannot proceed.** `{skills_output_folder}` contains 0 skills. Generate skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]."
+
+Read the `{skills_output_folder}` directory. Skills use a version-nested directory structure (see `knowledge/version-paths.md`).
+
+**Version-aware skill discovery:**
+1. Read `{skills_output_folder}/.export-manifest.json` if it exists. For each skill in `exports`, use `active_version` to resolve `{skill_package}` = `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/`
+2. For any subdirectory not covered by the manifest, check for an `active` symlink at `{skills_output_folder}/{dir_name}/active` — resolve to `{skill_group}/active/{dir_name}/`
+3. Fall back to flat path `{skills_output_folder}/{dir_name}/` for unmigrated skills
+
+For each resolved skill package, check for the presence of `SKILL.md`, `metadata.json`, and `bmad-skill-manifest.yaml`. If `bmad-skill-manifest.yaml` is missing in the resolved package, log "Skipping `{dir_name}` — missing bmad-skill-manifest.yaml" and exclude from inventory (do not spawn a subagent).
+
+**Non-symlink `active` check:** When resolving via the `active` symlink pattern (case 2 above), perform an explicit `is_symlink` check on `{skills_output_folder}/{dir_name}/active`. If the path exists but is NOT a symlink, log "Skipping `{dir_name}` — `active` is not a symlink (repair with [SKF-update-skill])" and treat as missing.
+
+**Orphan-versions detection:** For any `{skills_output_folder}/{dir_name}/` that contains subdirectories matching semver (`^\d+\.\d+\.\d+`) but has no `active` symlink at all, emit: "**Error:** Skill `{dir_name}` has versions `{list_of_version_dirs}` but no `active` symlink — run [SKF-update-skill] to repair before re-running [VS]." Exclude the skill from inventory; count it toward the failure budget for the run summary.
+
+<!-- Subagent delegation: read metadata.json files in parallel, return compact JSON -->
+
+**Read all metadata.json files in parallel using subagents.** Launch up to **8 subagents concurrently** (batch larger inventories in rounds of 8 — the 8-way cap keeps the aggregate token window for the parent manageable while still parallelizing most typical stack sizes; tune in a future minor if inventories routinely exceed ~40 skills). Each subagent receives one resolved skill package path and MUST:
+1. Read `{skill_package}/metadata.json`
+2. ONLY return this compact JSON — no prose, no extra commentary:
+
+```json
+{
+  "skill_name": "...",
+  "language": "...",
+  "confidence_tier": "...",
+  "exports_documented": 0,
+  "source_repo": "...",
+  "source_root": "..."
+}
+```
+
+Parent collects all subagent JSON summaries. Fields map directly from metadata.json:
+- `skill_name` ← `name`
+- `language` ← `language`
+- `confidence_tier` ← `confidence_tier`
+- `exports_documented` ← `stats.exports_documented`
+- `source_repo` ← `source_repo` (or empty string if absent)
+- `source_root` ← `source_root` (or empty string if absent)
+
+**Subagent JSON schema validation:** For each subagent response, require keys `skill_name`, `language`, and an integer `exports_documented`. Wrap each JSON parse in try/catch. On parse failure or missing required key, log "Skipping `{dir_name}` — metadata.json unparseable (skill may be under active modification)" and exclude from the inventory. If more than **20%** (the failure-budget threshold — chosen so a single malformed skill in a small 3-5 skill inventory does not trip the halt, while larger inventories still halt before evidence quality collapses) of subagent calls fail schema validation, HALT the workflow with: "Inventory scan unreliable — {failed_count}/{total_count} skills returned malformed metadata. Re-run [VS] after skills stabilize."
+
+**Capture mtime:** For each accepted skill, also record `metadata.json`'s mtime (via `stat`) into the inventory as `metadata_mtime`. Step-03 will re-verify this to detect mid-run modifications.
+
+**metadata_schema_version check:** For each accepted skill, read `metadata_schema_version` from `metadata.json`. If missing or below minimum (`1.0`), log "Skipping `{dir_name}` — metadata_schema_version `{value}` below minimum `1.0`. Re-run [SKF-update-skill] to migrate." and exclude from the inventory.
+
+**Build a skill inventory** as an internal list of all loaded skills with the fields above.
+
+**If a resolved skill package lacks SKILL.md or metadata.json:**
+- Log: "Skipping `{dir_name}` — missing SKILL.md or metadata.json"
+- Do not include in inventory
+
+### 3. Validate Minimum Requirements
+
+**Check skill count:**
+- At least 2 valid skills must exist (a stack requires multiple libraries)
+- If fewer than 2 → "**Cannot proceed.** Only {count} skill(s) found in `{skills_output_folder}`. A stack requires at least 2 skills. Generate more skills with [CS] Create Skill or [QS] Quick Skill, then re-run [VS]."
+- HALT workflow
+
+**Check forge_data_folder:**
+- Verify `forge_data_folder` was resolved from config.yaml and is non-empty
+- If undefined or empty → "**Cannot proceed.** `forge_data_folder` is not configured in config.yaml. Re-run [SF] Setup Forge to initialize."
+- HALT workflow
+
+**Check architecture document:**
+- Confirm it was loaded successfully in section 1
+- If not → HALT with error (should not reach here if section 1 validation passed)
+
+### 4. Create Feasibility Report
+
+This skill is the PRODUCER of the feasibility report schema defined in `{feasibilitySchemaRef}`. All outputs MUST conform to that schema — in particular: `schemaVersion: "1.0"`, the defined verdict token set (`Verified|Plausible|Risky|Blocked`; overall `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`), the filename pattern, and the section-heading order.
+
+**Compute filename variables:**
+- `project_slug`: slugify `project_name` (lowercase, hyphens only, no unicode, no whitespace)
+- `timestamp`: UTC `YYYYMMDD-HHmmss` captured at step-01 start
+- `outputFile` resolves to `{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md`
+- `outputFileLatest` resolves to `{forge_data_folder}/feasibility-report-{project_slug}-latest.md` (a copy, not a symlink — per schema)
+
+**Load** `{reportTemplate}` and stage the initial content.
+
+**Populate frontmatter (per shared schema — required keys):**
+- `schemaVersion: "1.0"`
+- `reportType: feasibility`
+- `projectName: "{project_name}"`
+- `projectSlug: "{project_slug}"`
+- `generatedAt: "{ISO-8601 UTC}"`
+- `generatedBy: skf-verify-stack`
+- `overallVerdict: "CONDITIONALLY_FEASIBLE"` (provisional until step-05 finalizes)
+- `coveragePercentage: 0`
+- `pairsVerified: 0`, `pairsPlausible: 0`, `pairsRisky: 0`, `pairsBlocked: 0`
+- `recommendationCount: 0`
+- `prdAvailable: true|false` (from section 1 validation)
+
+**Populate producer-local bookkeeping keys (not part of the consumer contract):**
+- `architectureDoc`, `prdDoc` (or "none"), `previousReport` (or empty string)
+- `skillsAnalyzed: {count}`
+- `stepsCompleted: ['step-01-init']`
+
+**Atomic write:** Pipe the staged content through `python3 {atomicWriteScript} write --target {outputFile}` and then again with `--target {outputFileLatest}`. Both writes use the same staged content. Do NOT use `rm`+rewrite; do NOT create a symlink for the `-latest` copy.
+
+### 5. Display Initialization Summary
+
+"**Stack Verification Initialized**
+
+| Field | Value |
+|-------|-------|
+| **Skills Loaded** | {count} |
+| **Architecture Doc** | {architecture_doc} |
+| **PRD Document** | {prd_doc or 'Not provided — requirements pass will be skipped'} |
+| **Previous Report** | {previousReport or 'Not provided — no delta comparison'} |
+
+**Skill Inventory:**
+
+| Skill | Language | Tier | Exports |
+|-------|----------|------|---------|
+| {skill_name} | {language} | {confidence_tier} | {exports_documented} |
+
+**Proceeding to coverage analysis...**"
+
+### 6. Auto-Proceed to Next Step
+
+Load, read the full file and then execute `{nextStepFile}`.
+

package/src/{workflows/verify-stack → skf-verify-stack}/steps-c/step-02-coverage.md

@@ -1,10 +1,10 @@
 ---
-name: 'step-02-coverage'
-description: 'Pass 1 — check that a generated skill exists for every technology referenced in the architecture document'
-
 nextStepFile: './step-03-integrations.md'
-coveragePatternsData: '../data/coverage-patterns.md'
-outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+coveragePatternsData: 'references/coverage-patterns.md'
+feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
+atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.md'
 ---
 
 # Step 2: Technology Coverage Analysis
@@ -13,41 +13,10 @@ outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
 
 Verify that a generated skill exists for every technology, library, or framework referenced in the architecture document. Produce a coverage matrix showing which technologies are covered and which are missing. Detect extra skills not referenced in the architecture.
 
-## 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 coverage analysis
-- ✅ Every technology reference must trace to actual text in the architecture document
-- ✅ Matching must be precise — do not guess or infer technologies not explicitly mentioned
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on technology-to-skill coverage mapping
-- 🚫 FORBIDDEN to analyze API surfaces or integration compatibility — that is Step 03
-- 🚫 FORBIDDEN to evaluate requirements — that is Step 04
-- 💬 Coverage verdicts must be binary: Covered or Missing — no ambiguity
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Extract technology references from architecture document using {coveragePatternsData}
-- 💾 Build and display coverage matrix with Covered/Missing verdicts
-- 📖 Append Coverage Matrix section to {outputFile}
-- 🚫 Only coverage mapping — no integration analysis, no requirements checking
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Architecture document content, skill inventory from Step 01, coverage patterns data
-- Focus: Technology-to-skill matching only
-- Limits: Do not read SKILL.md in detail — use metadata.json for name and source_repo matching only
-- Dependencies: Step 01 must have loaded skill inventory and validated architecture document
+- Focus only on technology-to-skill coverage mapping — do not analyze API surfaces (Step 03) or requirements (Step 04)
+- Coverage verdicts must be binary: Covered or Missing
 
 ## MANDATORY SEQUENCE
 
@@ -86,7 +55,12 @@ For each referenced technology in the list:
 **Check if a matching skill exists** in the skill inventory from Step 01.
 - Match by skill name (case-insensitive)
 - Match by alias from {coveragePatternsData}
-- Match by `source_repo` or `source_root` field in metadata.json if skill name differs from technology name
+- Match by `source_repo` or `source_root` field in metadata.json if skill name differs from technology name, using this algorithm:
+  1. For `source_repo`: extract the basename (last URL segment after the final `/`), strip any trailing `.git` suffix, lowercase
+  2. For `source_root`: take the last path segment (after the final `/` or `\`), lowercase
+  3. Lowercase each architecture tech token
+  4. Compare the resulting basenames/segments against the tech tokens via case-insensitive equality (no substring/fuzzy matching)
+  5. A match on either `source_repo` basename or `source_root` last segment counts as a hit
 
 **Assign verdict:**
 - **Covered** — a matching skill exists in the inventory
@@ -98,11 +72,15 @@ Build the coverage matrix as a structured table.
 
 Check if any skills in the inventory are NOT referenced in the architecture document.
 
+**Subdivide into two categories (both informational — not errors):**
+- **Extra (unreferenced)** — The skill's `source_repo` / `source_root` resolves cleanly (both non-empty and well-formed), but no architecture document tech token matches it.
+- **Orphan (source_repo unresolvable)** — The skill's `source_repo` is empty, malformed (not a valid URL-like string), OR its basename cannot be deterministically extracted. Cross-reference against architecture tokens is not possible for this skill.
+
 **For each extra skill:**
-- Mark as **Extra** (informational — not an error)
-- Note: "Skill `{skill_name}` exists but is not referenced in the architecture document"
+- If `source_repo` resolves → mark as **Extra (unreferenced)**, note: "Skill `{skill_name}` exists and has a resolvable `source_repo`, but no architecture reference was found."
+- If `source_repo` does not resolve → mark as **Orphan (source_repo unresolvable)**, note: "Skill `{skill_name}` has no resolvable `source_repo` — cannot cross-reference against architecture. Re-run [CS] or update the skill's metadata."
 
-Extra skills are informational only. They do not affect the coverage verdict.
+Extra and Orphan skills are informational only. They do not affect the coverage verdict.
 
 ### 5. Display Coverage Results
 
@@ -129,16 +107,17 @@ Extra skills are informational only. They do not affect the coverage verdict.
 
 ### 6. Append to Report
 
-Write the **Coverage Matrix** section to `{outputFile}`:
+Write the **Coverage Analysis** section to `{outputFile}` (see `{feasibilitySchemaRef}` — section headings are fixed and ordered: `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources`):
 - Include the full coverage table
 - Include coverage percentage
 - Include missing skill recommendations
-- Include extra skills list
-- Update frontmatter: append `'step-02-coverage'` to `stepsCompleted`, set `coverage_percentage`
+- Include the Extra (unreferenced) and Orphan (source_repo unresolvable) subdivisions from section 4
+- Update frontmatter: append `'step-02-coverage'` to `stepsCompleted`; set `coveragePercentage` (integer 0..100)
+- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 7. Auto-Proceed to Next Step
 
-{IF coverage_percentage is 0%:}
+{IF coveragePercentage is 0%:}
 "**⚠️ 0% coverage — no matching skills found for any referenced technology.** All subsequent analysis (integration, requirements) will be vacuous and produce empty tables.
 
 **Recommended:** Generate skills with [CS] or [QS] for your architecture technologies, then re-run [VS].
@@ -150,32 +129,8 @@ Write the **Coverage Matrix** section to `{outputFile}`:
 
   Load, read the full file and then execute `{nextStepFile}`.
 
-{IF coverage_percentage is NOT 0%:}
+{IF coveragePercentage is not 0:}
 "**Proceeding to integration analysis...**"
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Coverage patterns loaded from {coveragePatternsData}
-- All technology references extracted from architecture document with section citations
-- Every referenced technology cross-referenced against skill inventory
-- Coverage matrix displayed with binary Covered/Missing verdicts
-- Extra skills detected and reported as informational
-- Missing skills have actionable recommendations (run [CS] or [QS])
-- Coverage Matrix section appended to {outputFile}
-- Auto-proceeded to step 03
-
-### ❌ SYSTEM FAILURE:
-
-- Inventing technologies not mentioned in the architecture document
-- Ambiguous verdicts (anything other than Covered or Missing)
-- Analyzing API surfaces or skill content in detail (that is Step 03)
-- Not providing actionable recommendations for missing skills
-- 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/skf-verify-stack/steps-c/step-03-integrations.md

@@ -0,0 +1,179 @@
+---
+nextStepFile: './step-04-requirements.md'
+integrationRulesData: 'references/integration-verification-rules.md'
+coveragePatternsData: 'references/coverage-patterns.md'
+feasibilitySchemaRef: 'src/shared/references/feasibility-report-schema.md'
+atomicWriteScript: '{project-root}/src/shared/scripts/skf-atomic-write.py'
+outputFile: '{forge_data_folder}/feasibility-report-{project_slug}-{timestamp}.md'
+outputFileLatest: '{forge_data_folder}/feasibility-report-{project_slug}-latest.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.
+
+## Rules
+
+- Focus only on integration pair verification using skill API surfaces
+- Do not evaluate requirements coverage (Step 04) or parse Mermaid diagrams
+- Every verdict must include evidence citations from the skills
+
+## 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
+
+**Source preference:** If a stack skill assembled by `skf-create-stack-skill` is present in the inventory and its manifest (`bmad-skill-manifest.yaml` or its `metadata.json`) declares `integration_patterns`, use THAT as the primary source of integration claims. Record `source: stack manifest` on each resulting pair. Fall back to prose co-mention (below) only when no such manifest is available, and record `source: prose co-mention` on those pairs.
+
+Parse the architecture document for statements describing two or more technologies working together.
+
+**Detection method — prose-based co-mention analysis (fallback only):**
+- 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 — Mermaid Diagram Handling:** See `{coveragePatternsData}` → "Mermaid Diagram Handling" for the canonical rule (single source of truth). Summary: do NOT parse Mermaid diagram syntax for co-mention detection; use only prose text.
+
+**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
+
+<!-- Subagent delegation: read SKILL.md files in parallel, return compact JSON -->
+
+For each library in an integration pair, delegate SKILL.md reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch if needed — same 8-way cap as step-01 §2; keeps aggregate token window manageable while still parallelizing typical stack sizes). Each subagent receives one skill's SKILL.md path and MUST:
+1. Read the SKILL.md file
+2. Extract the API surface
+3. ONLY return this compact JSON — no prose, no extra commentary:
+
+```json
+{
+  "skill_name": "...",
+  "language": "...",
+  "exports": ["functionName(params): ReturnType", "..."],
+  "protocols_inferred": ["HTTP", "gRPC", "WebSocket", "message queue", "file I/O", "IPC"],
+  "data_formats_inferred": ["JSON", "protobuf", "CSV", "binary", "streaming"]
+}
+```
+
+**Extraction rules for subagents:**
+- `skill_name`, `language`: mirror the skill's metadata fields
+- `exports`: exported functions with signatures, exported types/interfaces/classes (extracted from SKILL.md prose)
+- `protocols_inferred`: best-effort prose scan — protocol tokens mentioned in SKILL.md descriptions/examples. NOT a declared field in `metadata.json`
+- `data_formats_inferred`: best-effort prose scan — format tokens mentioned in SKILL.md descriptions/examples. NOT a declared field in `metadata.json`
+- If a field has no matches, return an empty array `[]`
+
+**CRITICAL — these fields are inferred, not declared.** `protocols` and `data_formats` do not exist in any skill's `metadata.json`. Treat them as weak evidence from prose scanning only. When either list is used to justify compatibility in Check 2, the per-pair verdict MUST be capped at `Plausible` (see the schema's producer obligations — `src/shared/references/feasibility-report-schema.md`).
+
+**Schema validation (parent):** Each subagent response must contain the required keys (`skill_name`, `language`, `exports`). Reject responses missing required keys and exclude that skill from pair evaluation; HALT if more than **20%** (same failure-budget threshold as step-01 §2; see the justification there) of subagent calls return malformed JSON.
+
+**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context.
+
+**From metadata.json (read in parent — lightweight), also extract:**
+- `language` — primary programming language (authoritative — overrides subagent `language` if they disagree)
+- `exports` — export names array (populated for individual skills; empty for stack skills)
+- `stats.exports_documented` — export count
+- `confidence_tier` — extraction confidence level
+
+**mtime re-verification:** Re-stat each `metadata.json` and compare against the mtime captured in step-01. If any mtime moved during the run, abort any pair involving that skill with rationale "skill modified mid-run — re-run [VS]".
+
+Store collected API surface summaries for cross-referencing.
+
+**Integration-evidence source preference:** If the stack was assembled by `skf-create-stack-skill` and a stack manifest (e.g., `integration_patterns` block in the stack skill's `bmad-skill-manifest.yaml` or `metadata.json`) is present in the inventory, use that as the authoritative integration source and cite `source: stack manifest` in each verdict. Fall back to prose co-mention only when no manifest is available, and cite `source: prose co-mention`.
+
+### 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 (best-effort prose scan):**
+- Uses only the `protocols_inferred` / `data_formats_inferred` lists surfaced by the subagent prose scan — these are NOT declared metadata fields
+- Both prose-scanned lists share a protocol token → treat as inferred compatibility (cap verdict at `Plausible`)
+- Complementary tokens (e.g., "HTTP client" in one, "HTTP server" in the other) → inferred compatibility (cap at `Plausible`)
+- Neither skill surfaces any protocol token, or tokens appear to conflict with no adapter mentioned → flag as risk
+- Do NOT assert that protocols come from a declared schema field; when prose evidence is all that's available, the per-pair verdict MUST cap at `Plausible`
+
+**Check 3 — Type Compatibility:**
+- Shared types or compatible serialization formats (cited from `exports` signatures) → compatible
+- Incompatible type systems with no conversion layer → flag as risk
+
+**Check 4 — Documentation Cross-Reference (REQUIRED for `Verified`):**
+- Search Skill A's SKILL.md for a literal substring/name citation of Skill B's library name (or an explicit alias declared in that skill's metadata)
+- Search Skill B's SKILL.md for the reciprocal citation
+- If a literal citation is found in at least one direction → Check 4 PASSES; record the exact cited substring and its location as evidence
+- If neither skill literally cites the other → Check 4 FAILS (weak/missing evidence); per-pair verdict MUST be capped at `Plausible` regardless of Checks 1–3 outcomes
+
+**Assign verdict per pair (per `src/shared/references/feasibility-report-schema.md`):**
+- **Verified** — Checks 1, 3 pass with declared evidence AND Check 4 passes with a literal substring/name citation recorded in the evidence block. Check 2 is best-effort only; it cannot by itself promote a pair to `Verified`.
+- **Plausible** — Checks pass, but at least one relies on inferred evidence (e.g., Check 2 prose scan) OR Check 4 is weak/missing. This is the cap whenever Check 4 fails.
+- **Risky** — At least one check flags an incompatibility that a workaround may resolve (bridge layer, adapter, serialization shim).
+- **Blocked** — Fundamental incompatibility: language barrier with no bridge documented anywhere in the inventory, or type/protocol mismatch with no adapter mentioned.
+
+**Each verdict MUST include:**
+- Which checks passed and which flagged
+- Evidence citations: specific exports, types, or literal substrings from the skills
+- `source: stack manifest` or `source: prose co-mention` tag (per section 3)
+- For `Verified`: the exact Check 4 literal citation (e.g., `"see also: {lib_b}"` quoted from Skill A's SKILL.md, line N)
+- **Tier annotation:** For each contributing skill, append `(evidence from Tier {n} skill)` citing that skill's `confidence_tier` (e.g., `(evidence from Tier 1 skill)`). This lets reviewers weigh evidence strength by extraction confidence.
+
+**Cycle detection (after all pairs evaluated):** Build a directed pair graph where an edge `A → B` exists when A cites B via Check 4. Run cycle detection (DFS with visited + recursion stack). For each cycle found, append a synthetic row to the verdict table with verdict `Risky` and rationale "circular integration dependency detected: `{A → B → C → A}`". Do not otherwise modify the individual pair verdicts.
+
+### 5. Display Integration Results
+
+"**Pass 2: Integration Verification**
+
+| Library A | Library B | Context | Source | Verdict | Evidence |
+|-----------|-----------|---------|--------|---------|----------|
+| {lib_a} | {lib_b} | {brief context} | {stack manifest / prose co-mention} | {Verified/Plausible/Risky/Blocked} | {key evidence, including Check 4 literal citation if Verified} |
+
+**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}` (heading is fixed — consumers grep for `## Integration Verdicts`; the table header MUST be the canonical `| lib_a | lib_b | verdict | rationale |` per `{feasibilitySchemaRef}`; the skill-local display table with the extra Context/Source/Evidence columns can be rendered beneath it for human readers):
+- Emit the canonical `| lib_a | lib_b | verdict | rationale |` table first (verdict tokens MUST be one of `Verified`, `Plausible`, `Risky`, `Blocked` — case-sensitive)
+- Include the extended table with Context, Source, and Evidence columns below it
+- Include recommendations for Risky and Blocked pairs (Blocked recommendations MUST cite a named candidate per step-05 H6, or the explicit no-candidate notice)
+- Update frontmatter: append `'step-03-integrations'` to `stepsCompleted`; set `pairsVerified`, `pairsPlausible`, `pairsRisky`, `pairsBlocked` counts
+- Pipe the updated full content through `python3 {atomicWriteScript} write --target {outputFile}` and again with `--target {outputFileLatest}`
+
+### 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}`.
+