governance-matrix-validator
Use when auditing CI governance workflows, triaging cross-repo script dependencies across toolforge, sigil, and cic-ingestion, or investigating masked failures from permissive CI job configurations.
SKILL.mdskills/governance-matrix-validator/SKILL.md
GitHubGovernance Matrix Validator Specification
ID: governance-matrix-validator
Version: 0.1.0
Status: Active
Owner: Toolforge Core
Purpose
Validate CI governance matrix workflows against physical repository states. Unmasks hidden errors suppressed by continue-on-error: true and verifies cross-repository script and dependency contracts across toolforge, sigil, and cic-ingestion.
Trigger
Exact prompts that invoke this skill:
governance-matrix-validator
/governance-matrix-validator
validate governance gates
check governance matrix for masked failures
Input Schema
interface GovernanceMatrixValidatorInput {
workflowPath?: string; // Optional. Path to workflow file (default: .github/workflows/ci-governance-matrix.yml)
repoScope?: string[]; // Optional. Subset of repos to audit (default: ['toolforge', 'sigil', 'cic-ingestion'])
unmaskOnly?: boolean; // Optional. Flag only continue-on-error masking without checking repo disk targets
}
Output Schema
interface GovernanceMatrixValidatorOutput {
status: "HEALTHY" | "DEGRADED" | "ACTION_REQUIRED" | "ERROR";
maskedFailures: Array<{
jobName: string;
stepName: string;
reason: string;
}>;
repoFindings: Array<{
repo: "toolforge" | "sigil" | "cic-ingestion" | string;
issueCode: string;
severity: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
missingTarget: string;
suggestedFix: string;
}>;
recommendedActions: string[];
timestamp: string;
}
Error Handling
See Skill Operator Guide — Error Handling for standard error codes.
Additional error codes:
| Code | Message | Handler |
|---|---|---|
GOV_WORKFLOW_NOT_FOUND |
Specified workflow file does not exist | Verify path in .github/workflows/ |
GOV_REPO_NOT_MOUNTED |
Linked sibling repo directory is inaccessible | Confirm checkout paths for sigil and cic-ingestion |
GOV_MASKED_FAILURE_DETECTED |
Job contains continue-on-error hiding critical steps | Remove permissive flag or fix upstream failure |
Core Rationalizations & Red Flags
| Excuse / Rationalization | Reality |
|---|---|
| "The workflow run is green, so all governance gates pass" | continue-on-error: true conceals failing steps. Always inspect underlying step outcomes. |
| "A missing script in a sibling repo is an external issue" | Matrix workflows execute across repo boundaries; missing scripts break matrix guarantees. |
| "Temporary masking in CI is harmless during refactors" | Masked checks easily become permanent blind spots. Fix the root cause or skip the job explicitly. |
Full Reference
For Setup, Requirements, Configuration, Testing, Troubleshooting, and Integration:
→ See Skill Operator Guide
For workflow examples and deep integration patterns:
→ See docs/USAGE.md