# The five validation checks Full detail for each of the five validation checks the validator runs. Load this when actually executing a scan — the SKILL.md keeps the entry points and the severity ladder; this file keeps the procedures. --- ## Check 1: Directive Conflicts **Purpose:** Find contradictions between imperative statements across skills and rules. **Process:** 1. **Extract Directives** - Scan all SKILL.md, rules, and commands for imperative statements - Target keywords: `MUST`, `NEVER`, `ALWAYS`, `NO`, `REQUIRED`, `MANDATORY`, `FORBIDDEN`, `DO NOT` - Extract the full sentence containing each directive - Record: file path, line context, directive text 2. **Categorize Directives by Topic** - Group directives by what they govern: - Testing (when to test, what to test, how to test) - Code generation (when to write code, what patterns) - Deployment (when to deploy, prerequisites) - Review (what to review, how to review) - Documentation (what to document, when) - Git (branching, committing, PRs) - Security (secrets, auth, validation) - Process (ordering, gates, approvals) 3. **Cross-Check for Contradictions** - Within each topic, compare directives pairwise - Flag when: - One says MUST and another says NEVER for the same action - One says ALWAYS and another says exception/skip for the same context - Scope overlap creates ambiguity (general rule vs specific skill) 4. **Output Format** ``` CONFLICTS: [ERROR] C-001: Testing Contradiction build-tdd: "NO production code without a failing test FIRST" build-scaffold: "Generate project boilerplate with initial test infrastructure" Analysis: Scaffold generates code before tests exist. Is scaffold exempt from TDD? Suggested Resolution: Document scaffold as a TDD-exempt bootstrap phase, or require scaffold to generate failing tests first. [WARNING] C-002: Fact-Checking Overlap support-debug: "FACT-CHECK FIRST: verify the reported behavior" rules/common/verification.md: "verify via context7 or websearch BEFORE proceeding" Analysis: Not a contradiction, but unclear which takes precedence when both apply. Suggested Resolution: Clarify that verification rule is the authority, support-debug applies it specifically to bug reports. ``` 5. **Known Acceptable Conflicts** - Some conflicts are intentional (e.g., `/hotfix` explicitly skips certain gates) - These must be documented as intentional exceptions - If documented, report as INFO not ERROR - If undocumented, report as WARNING --- ## Check 2: I/O Graph Integrity **Purpose:** Verify that the I/O protocol forms a valid directed acyclic graph (DAG). **Severity Baseline (READ FIRST — prevents false ERRORs):** I/O Contract is **OPTIONAL** per `references/common/skill-authoring.md`. Per that rule, fields are "Usually" required, not "Always". Apply this severity ladder when classifying any I/O finding: | Situation | Default severity | |---|---| | Skill has NO `## I/O Contract` section at all (pure methodology skill) | **INFO** — by design, do not escalate without evidence the omission breaks a workflow | | Skill has I/O Contract but omits one field (e.g., no `Feeds into`) | **INFO** — `Feeds into` is "Usually", not mandatory | | `Produces X` is declared but no skill lists `Requires X` (orphaned output) | **INFO** — asymmetric mirroring is allowed; only escalate if a real consumer is observed to fail | | `Requires X` is declared but NO skill produces X anywhere (broken pipeline) | **ERROR** — this genuinely breaks the workflow | | Cycle detected in the produces→requires graph (true deadlock) | **ERROR** | Only escalate to WARNING/ERROR when you can name the downstream skill that fails and how. "X is missing a row" is INFO; "skill Y will fail to find artifact X" is WARNING/ERROR. **Process:** 1. **Build the I/O Graph** - For each skill that declares I/O metadata, extract: - `Requires`: what artifacts it needs as input - `Produces`: what artifacts it creates as output - `Feeds into`: which skills consume its output - Skills WITHOUT an `## I/O Contract` section are treated as methodology-only nodes. Record their existence but do not flag the omission above INFO. - Build a directed graph: skill -> produces -> consumed by -> skill 2. **Check for Missing Producers** - For every `Requires` entry, verify at least one skill `Produces` it - Missing producer = gap in the pipeline (something needs input that nothing creates) ``` [ERROR] IO-001: Missing Producer quality-test-execution requires "test-plan.md" No skill produces "test-plan.md" Wait -- quality-test-plan produces this. Check naming match. ``` 3. **Check for Orphaned Outputs** - For every `Produces` entry, verify at least one skill or command references it (in `Requires`, in command flow, or in protocol body) - Orphaned output = artifact created but never referenced anywhere - **Default severity: INFO** (per Severity Baseline above). The artifact may be consumed by a command directly without the consumer-skill mirroring the row. - Escalate to WARNING only if the artifact is named in another skill's body as required and that skill would fail without it. ``` [INFO] IO-002: Orphaned Output (asymmetric mirroring) quality-security-audit produces "security audit report" deliver-deploy doesn't mirror it in `Requires`. `Feeds into` is "Usually", not mandatory. No workflow break observed. Action: Optional — add to deliver-deploy `Requires` if consumer-side visibility matters. No fix required. ``` 4. **Check for Skills Without I/O Contract (NOT a defect)** - Some skills are pure methodology and intentionally omit `## I/O Contract` (e.g., `build-tdd` — the agent owns its TDD methodology handoff, the calling command owns the orchestration). - **Default severity: INFO**. Note the omission for awareness; do not block. ``` [INFO] IO-005: Skill Omits I/O Contract by Design build-tdd has no `## I/O Contract` section. Per `references/common/skill-authoring.md`, I/O Contract is OPTIONAL for methodology-only skills. build-tdd's task scope and artifact paths are supplied by the calling command (/feature, /bugfix, /hotfix) and by the dispatched builder agent. Action: None. This is intentional design. ``` 5. **Check for Circular Dependencies** - Verify the graph is acyclic - Circular dependency = deadlock (A requires B's output, B requires A's output) ``` [ERROR] IO-003: Circular Dependency build-tdd requires architecture artifacts plan-architecture requires codebase analysis discover-codebase-analysis requires existing code build-tdd produces existing code Cycle: build-tdd -> plan-architecture -> discover-codebase-analysis -> build-tdd Note: This is a false positive -- discover-codebase-analysis is for EXISTING code, not code being built. Mark as checked. ``` 6. **Verify Artifact Path Consistency** - Check that artifact paths are consistent across skills - If one skill produces `.forge/work/{type}/{name}/test-plan.md` and another requires `test-plan.md`, flag the ambiguity ``` [WARNING] IO-004: Path Ambiguity quality-test-plan produces: ".forge/work/{type}/{name}/test-plan.md" quality-test-execution requires: "test plan" Recommend: Use consistent path references across skills. ``` --- ## Check 3: Responsibility Overlaps **Purpose:** Flag when multiple skills claim the same responsibility. **Process:** 1. **Extract Responsibility Claims** - From each skill's "Process" section, extract what it does - From each skill's "Covers" section, extract what it reviews - From rules, extract what they enforce 2. **Identify Overlaps** - Multiple skills claiming to do the same thing - Multiple rules enforcing the same constraint differently - A skill doing something that a rule also enforces 3. **Classify Overlaps** | Type | Severity | Example | |---|---|---| | **Redundant enforcement** | WARNING | Both code-review and security-audit check for secrets | | **Conflicting ownership** | ERROR | Both test-plan and tdd claim to write unit tests | | **Layered enforcement** | INFO | Rule sets standard, skill enforces it (this is correct design) | 4. **Output Format** ``` OVERLAPS: [WARNING] O-001: Fact-Checking Responsibility Claimed by: support-debug (Phase 0), rules/common/verification.md, quality-code-review Analysis: Three components all perform fact-checking. Suggested Resolution: verification.md is the authority on WHEN to fact-check. support-debug applies it to bug reports. quality-code-review applies it to reviews. Document this hierarchy explicitly. [INFO] O-002: Layered Security Enforcement rules/common/security.md: Sets security standards quality-security-audit: Enforces security standards in code review quality-code-review: Checks for secret exposure in critical pass Analysis: This is correct layered enforcement. No action needed. ``` --- ## Check 4: Gate Completeness **Purpose:** Verify every command transition has a defined quality gate. **Process:** 1. **Extract Command Flows** - Parse each command file for its skill sequence - Identify every transition between skills (skill A -> skill B) 2. **Check Gate Definitions** - For each transition, verify a gate is defined in `references/common/quality-gates.md` - Gate must specify: what is checked, pass criteria, fail action 3. **Flag Missing Gates** ``` [ERROR] G-001: Missing Gate /feature command: build-tdd -> quality-code-review No gate defined for this transition. Recommended: Define gate criteria (e.g., "all tests pass, no lint errors"). ``` 4. **Flag Undocumented Exemptions** - Some commands intentionally skip gates (e.g., `/hotfix` may skip brainstorming) - These MUST be documented as intentional - If a gate is skipped but not documented as intentional, flag it ``` [WARNING] G-002: Undocumented Gate Exemption /hotfix command skips gate between discover -> plan This may be intentional for emergency fixes, but it is not documented. Recommended: Add explicit exemption documentation: "Hotfix skips brainstorming gate because emergency fixes prioritize speed over design exploration." ``` 5. **Verify Gate Criteria Are Testable** - "Code must be good" is not a testable gate - "All tests pass, coverage > 80%, no critical lint errors" is testable - Flag vague gate criteria ``` [WARNING] G-003: Vague Gate Criteria Gate: architecture -> implementation Criteria: "Architecture artifacts reviewed" Issue: "Reviewed" is subjective. Recommended: "Architecture artifacts exist, contain API contracts, DB schema (if applicable), and system diagram. User has approved the approach." ``` --- ## Check 5: Post-Evolve Drift **Purpose:** After modifications, verify changed skills/rules are still consistent with the rest of the system. **Process:** 1. **Identify Modified Files** - Compare against last known validated state - Use git diff if available, or timestamp comparison - Focus validation on changed files and their connections 2. **Run Targeted Checks** - For each modified file: - Re-run Check 1 (directives) against all other files - Re-run Check 2 (I/O) for connected skills only - Re-run Check 3 (overlaps) for same-domain skills - Re-run Check 4 (gates) for commands that reference modified skill 3. **Output Format** ``` DRIFT: [ERROR] D-001: New Contradiction After /forge-evolve Modified: support-debug (added "ALWAYS verify with context7 before debugging") Conflicts with: rules/common/verification.md ("verify when UNCERTAIN, not always") Analysis: New directive is stricter than existing rule. Suggested Resolution: Align language -- either debug skill says "when uncertain" or verification rule says "always." [INFO] D-002: No Drift Detected Modified: deliver-deploy (updated smoke test section) All checks pass against connected skills and rules. ```