feat(contract-validator): add validate_workflow_integration tool (v5.7.1)
Domain Advisory Pattern Hardening - patch release to close gaps from v5.6.0/v5.7.0: ## Added - New `validate_workflow_integration` MCP tool validates domain plugins expose required advisory interfaces (gate command, review command, advisory agent) - New `MISSING_INTEGRATION` issue type for workflow integration validation - New `WorkflowIntegrationResult` Pydantic model for structured validation output - `integrates_with` field on viz-platform and data-platform in marketplace.json declaring projman integration metadata - 4 new test cases for workflow integration validation ## Fixed - scripts/setup.sh banner version updated from v5.1.0 to v5.7.1 ## Documentation - Updated mcp-tools-reference.md with new tool - Updated validation-rules.md with Workflow Integration Checks section - Added /design-gate, /design-review, /data-gate, /data-review to COMMANDS-CHEATSHEET - Added contract-validator to CONFIGURATION.md plugin table - Updated README.md Contract Validator tools table Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -131,6 +131,24 @@ class ContractValidatorMCPServer:
|
||||
"required": ["agent_name", "claude_md_path"]
|
||||
}
|
||||
),
|
||||
Tool(
|
||||
name="validate_workflow_integration",
|
||||
description="Validate that a domain plugin exposes the required advisory interfaces (gate command, review command, advisory agent) expected by projman's domain-consultation skill",
|
||||
inputSchema={
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"plugin_path": {
|
||||
"type": "string",
|
||||
"description": "Path to the domain plugin directory"
|
||||
},
|
||||
"domain_label": {
|
||||
"type": "string",
|
||||
"description": "The Domain/* label it claims to handle, e.g. Domain/Viz"
|
||||
}
|
||||
},
|
||||
"required": ["plugin_path", "domain_label"]
|
||||
}
|
||||
),
|
||||
# Report tools (to be implemented in #188)
|
||||
Tool(
|
||||
name="generate_compatibility_report",
|
||||
@@ -198,6 +216,8 @@ class ContractValidatorMCPServer:
|
||||
result = await self._validate_agent_refs(**arguments)
|
||||
elif name == "validate_data_flow":
|
||||
result = await self._validate_data_flow(**arguments)
|
||||
elif name == "validate_workflow_integration":
|
||||
result = await self._validate_workflow_integration(**arguments)
|
||||
elif name == "generate_compatibility_report":
|
||||
result = await self._generate_compatibility_report(**arguments)
|
||||
elif name == "list_issues":
|
||||
@@ -241,6 +261,10 @@ class ContractValidatorMCPServer:
|
||||
"""Validate agent data flow"""
|
||||
return await self.validation_tools.validate_data_flow(agent_name, claude_md_path)
|
||||
|
||||
async def _validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict:
|
||||
"""Validate domain plugin exposes required advisory interfaces"""
|
||||
return await self.validation_tools.validate_workflow_integration(plugin_path, domain_label)
|
||||
|
||||
# Report tool implementations (Issue #188)
|
||||
|
||||
async def _generate_compatibility_report(self, marketplace_path: str, format: str = "markdown") -> dict:
|
||||
|
||||
@@ -26,6 +26,7 @@ class IssueType(str, Enum):
|
||||
OPTIONAL_DEPENDENCY = "optional_dependency"
|
||||
UNDECLARED_OUTPUT = "undeclared_output"
|
||||
INVALID_SEQUENCE = "invalid_sequence"
|
||||
MISSING_INTEGRATION = "missing_integration"
|
||||
|
||||
|
||||
class ValidationIssue(BaseModel):
|
||||
@@ -65,6 +66,17 @@ class DataFlowResult(BaseModel):
|
||||
issues: list[ValidationIssue] = []
|
||||
|
||||
|
||||
class WorkflowIntegrationResult(BaseModel):
|
||||
"""Result of workflow integration validation for domain plugins"""
|
||||
plugin_name: str
|
||||
domain_label: str
|
||||
valid: bool
|
||||
gate_command_found: bool
|
||||
review_command_found: bool
|
||||
advisory_agent_found: bool
|
||||
issues: list[ValidationIssue] = []
|
||||
|
||||
|
||||
class ValidationTools:
|
||||
"""Tools for validating plugin compatibility and agent references"""
|
||||
|
||||
@@ -336,3 +348,107 @@ class ValidationTools:
|
||||
)
|
||||
|
||||
return result.model_dump()
|
||||
|
||||
async def validate_workflow_integration(self, plugin_path: str, domain_label: str) -> dict:
|
||||
"""
|
||||
Validate that a domain plugin exposes required advisory interfaces.
|
||||
|
||||
Checks for:
|
||||
- Gate command (e.g., /design-gate, /data-gate) - REQUIRED
|
||||
- Review command (e.g., /design-review, /data-review) - recommended
|
||||
- Advisory agent referencing the domain label - recommended
|
||||
|
||||
Args:
|
||||
plugin_path: Path to the domain plugin directory
|
||||
domain_label: The Domain/* label it claims to handle (e.g., Domain/Viz)
|
||||
|
||||
Returns:
|
||||
Validation result with found interfaces and issues
|
||||
"""
|
||||
plugin_path_obj = Path(plugin_path)
|
||||
issues = []
|
||||
|
||||
# Extract plugin name from path
|
||||
plugin_name = plugin_path_obj.name
|
||||
if not plugin_path_obj.exists():
|
||||
return {
|
||||
"error": f"Plugin directory not found: {plugin_path}",
|
||||
"plugin_path": plugin_path,
|
||||
"domain_label": domain_label
|
||||
}
|
||||
|
||||
# Extract domain short name from label (e.g., "Domain/Viz" -> "viz", "Domain/Data" -> "data")
|
||||
domain_short = domain_label.split("/")[-1].lower() if "/" in domain_label else domain_label.lower()
|
||||
|
||||
# Check for gate command
|
||||
commands_dir = plugin_path_obj / "commands"
|
||||
gate_command_found = False
|
||||
gate_patterns = ["pass", "fail", "PASS", "FAIL", "Binary pass/fail", "gate"]
|
||||
|
||||
if commands_dir.exists():
|
||||
for cmd_file in commands_dir.glob("*.md"):
|
||||
if "gate" in cmd_file.name.lower():
|
||||
# Verify it's actually a gate command by checking content
|
||||
content = cmd_file.read_text()
|
||||
if any(pattern in content for pattern in gate_patterns):
|
||||
gate_command_found = True
|
||||
break
|
||||
|
||||
if not gate_command_found:
|
||||
issues.append(ValidationIssue(
|
||||
severity=IssueSeverity.ERROR,
|
||||
issue_type=IssueType.MISSING_INTEGRATION,
|
||||
message=f"Plugin '{plugin_name}' lacks a gate command for domain '{domain_label}'",
|
||||
location=str(commands_dir),
|
||||
suggestion=f"Create commands/{domain_short}-gate.md with binary PASS/FAIL output"
|
||||
))
|
||||
|
||||
# Check for review command
|
||||
review_command_found = False
|
||||
if commands_dir.exists():
|
||||
for cmd_file in commands_dir.glob("*.md"):
|
||||
if "review" in cmd_file.name.lower() and "gate" not in cmd_file.name.lower():
|
||||
review_command_found = True
|
||||
break
|
||||
|
||||
if not review_command_found:
|
||||
issues.append(ValidationIssue(
|
||||
severity=IssueSeverity.WARNING,
|
||||
issue_type=IssueType.MISSING_INTEGRATION,
|
||||
message=f"Plugin '{plugin_name}' lacks a review command for domain '{domain_label}'",
|
||||
location=str(commands_dir),
|
||||
suggestion=f"Create commands/{domain_short}-review.md for detailed audits"
|
||||
))
|
||||
|
||||
# Check for advisory agent
|
||||
agents_dir = plugin_path_obj / "agents"
|
||||
advisory_agent_found = False
|
||||
|
||||
if agents_dir.exists():
|
||||
for agent_file in agents_dir.glob("*.md"):
|
||||
content = agent_file.read_text()
|
||||
# Check if agent references the domain label or gate command
|
||||
if domain_label in content or f"{domain_short}-gate" in content.lower() or "advisor" in agent_file.name.lower() or "reviewer" in agent_file.name.lower():
|
||||
advisory_agent_found = True
|
||||
break
|
||||
|
||||
if not advisory_agent_found:
|
||||
issues.append(ValidationIssue(
|
||||
severity=IssueSeverity.WARNING,
|
||||
issue_type=IssueType.MISSING_INTEGRATION,
|
||||
message=f"Plugin '{plugin_name}' lacks an advisory agent for domain '{domain_label}'",
|
||||
location=str(agents_dir) if agents_dir.exists() else str(plugin_path_obj),
|
||||
suggestion=f"Create agents/{domain_short}-advisor.md referencing '{domain_label}'"
|
||||
))
|
||||
|
||||
result = WorkflowIntegrationResult(
|
||||
plugin_name=plugin_name,
|
||||
domain_label=domain_label,
|
||||
valid=gate_command_found, # Only gate is required for validity
|
||||
gate_command_found=gate_command_found,
|
||||
review_command_found=review_command_found,
|
||||
advisory_agent_found=advisory_agent_found,
|
||||
issues=issues
|
||||
)
|
||||
|
||||
return result.model_dump()
|
||||
|
||||
@@ -254,3 +254,153 @@ async def test_validate_data_flow_missing_producer(validation_tools, tmp_path):
|
||||
# Should have warning about missing producer
|
||||
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
|
||||
assert len(warning_issues) > 0
|
||||
|
||||
|
||||
# --- Workflow Integration Tests ---
|
||||
|
||||
@pytest.fixture
|
||||
def domain_plugin_complete(tmp_path):
|
||||
"""Create a complete domain plugin with gate, review, and advisory agent"""
|
||||
plugin_dir = tmp_path / "viz-platform"
|
||||
plugin_dir.mkdir()
|
||||
(plugin_dir / ".claude-plugin").mkdir()
|
||||
(plugin_dir / "commands").mkdir()
|
||||
(plugin_dir / "agents").mkdir()
|
||||
|
||||
# Gate command with PASS/FAIL pattern
|
||||
gate_cmd = plugin_dir / "commands" / "design-gate.md"
|
||||
gate_cmd.write_text("""# /design-gate
|
||||
|
||||
Binary pass/fail validation gate for design system compliance.
|
||||
|
||||
## Output
|
||||
|
||||
- **PASS**: All design system checks passed
|
||||
- **FAIL**: Design system violations detected
|
||||
""")
|
||||
|
||||
# Review command
|
||||
review_cmd = plugin_dir / "commands" / "design-review.md"
|
||||
review_cmd.write_text("""# /design-review
|
||||
|
||||
Comprehensive design system audit.
|
||||
""")
|
||||
|
||||
# Advisory agent
|
||||
agent = plugin_dir / "agents" / "design-reviewer.md"
|
||||
agent.write_text("""# design-reviewer
|
||||
|
||||
Design system compliance auditor.
|
||||
|
||||
Handles issues with `Domain/Viz` label.
|
||||
""")
|
||||
|
||||
return str(plugin_dir)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def domain_plugin_missing_gate(tmp_path):
|
||||
"""Create domain plugin with review and agent but no gate command"""
|
||||
plugin_dir = tmp_path / "data-platform"
|
||||
plugin_dir.mkdir()
|
||||
(plugin_dir / ".claude-plugin").mkdir()
|
||||
(plugin_dir / "commands").mkdir()
|
||||
(plugin_dir / "agents").mkdir()
|
||||
|
||||
# Review command (but no gate)
|
||||
review_cmd = plugin_dir / "commands" / "data-review.md"
|
||||
review_cmd.write_text("""# /data-review
|
||||
|
||||
Data integrity audit.
|
||||
""")
|
||||
|
||||
# Advisory agent
|
||||
agent = plugin_dir / "agents" / "data-advisor.md"
|
||||
agent.write_text("""# data-advisor
|
||||
|
||||
Data integrity advisor for Domain/Data issues.
|
||||
""")
|
||||
|
||||
return str(plugin_dir)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def domain_plugin_minimal(tmp_path):
|
||||
"""Create minimal plugin with no commands or agents"""
|
||||
plugin_dir = tmp_path / "minimal-plugin"
|
||||
plugin_dir.mkdir()
|
||||
(plugin_dir / ".claude-plugin").mkdir()
|
||||
|
||||
readme = plugin_dir / "README.md"
|
||||
readme.write_text("# Minimal Plugin\n\nNo commands or agents.")
|
||||
|
||||
return str(plugin_dir)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_validate_workflow_integration_complete(validation_tools, domain_plugin_complete):
|
||||
"""Test complete domain plugin returns valid with all interfaces found"""
|
||||
result = await validation_tools.validate_workflow_integration(
|
||||
domain_plugin_complete,
|
||||
"Domain/Viz"
|
||||
)
|
||||
|
||||
assert "error" not in result
|
||||
assert result["valid"] is True
|
||||
assert result["gate_command_found"] is True
|
||||
assert result["review_command_found"] is True
|
||||
assert result["advisory_agent_found"] is True
|
||||
assert len(result["issues"]) == 0
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_validate_workflow_integration_missing_gate(validation_tools, domain_plugin_missing_gate):
|
||||
"""Test plugin missing gate command returns invalid with ERROR"""
|
||||
result = await validation_tools.validate_workflow_integration(
|
||||
domain_plugin_missing_gate,
|
||||
"Domain/Data"
|
||||
)
|
||||
|
||||
assert "error" not in result
|
||||
assert result["valid"] is False
|
||||
assert result["gate_command_found"] is False
|
||||
assert result["review_command_found"] is True
|
||||
assert result["advisory_agent_found"] is True
|
||||
|
||||
# Should have one ERROR for missing gate
|
||||
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
|
||||
assert len(error_issues) == 1
|
||||
assert "gate" in error_issues[0]["message"].lower()
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_validate_workflow_integration_minimal(validation_tools, domain_plugin_minimal):
|
||||
"""Test minimal plugin returns invalid with multiple issues"""
|
||||
result = await validation_tools.validate_workflow_integration(
|
||||
domain_plugin_minimal,
|
||||
"Domain/Test"
|
||||
)
|
||||
|
||||
assert "error" not in result
|
||||
assert result["valid"] is False
|
||||
assert result["gate_command_found"] is False
|
||||
assert result["review_command_found"] is False
|
||||
assert result["advisory_agent_found"] is False
|
||||
|
||||
# Should have one ERROR (gate) and two WARNINGs (review, agent)
|
||||
error_issues = [i for i in result["issues"] if i["severity"].value == "error"]
|
||||
warning_issues = [i for i in result["issues"] if i["severity"].value == "warning"]
|
||||
assert len(error_issues) == 1
|
||||
assert len(warning_issues) == 2
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_validate_workflow_integration_nonexistent_plugin(validation_tools, tmp_path):
|
||||
"""Test error when plugin directory doesn't exist"""
|
||||
result = await validation_tools.validate_workflow_integration(
|
||||
str(tmp_path / "nonexistent"),
|
||||
"Domain/Test"
|
||||
)
|
||||
|
||||
assert "error" in result
|
||||
assert "not found" in result["error"].lower()
|
||||
|
||||
Reference in New Issue
Block a user