gh-epieczko-betty/skills/artifact.validate/README.md

artifact.validate

Automated artifact validation against structure, schema, and quality criteria.

Purpose

The artifact.validate skill provides comprehensive validation of artifacts to ensure:

• Correct syntax (YAML/Markdown)
• Complete metadata
• Required sections present
• No placeholder content
• Schema compliance (when applicable)
• Quality standards met

Features

✅ Syntax Validation: YAML and Markdown format checking ✅ Metadata Validation: Document control completeness ✅ Section Validation: Required sections verification ✅ TODO Detection: Placeholder and incomplete content identification ✅ Schema Validation: JSON schema compliance (when provided) ✅ Quality Scoring: 0-100 quality score with breakdown ✅ Strict Mode: Enforce all recommendations ✅ Detailed Reporting: Actionable validation reports

Usage

Basic Validation

python3 skills/artifact.validate/artifact_validate.py <artifact-path>

With Artifact Type

python3 skills/artifact.validate/artifact_validate.py \
  my-artifact.yaml \
  --artifact-type business-case

Strict Mode

python3 skills/artifact.validate/artifact_validate.py \
  my-artifact.yaml \
  --strict

Strict mode treats warnings as errors. Useful for:

• CI/CD pipeline gates
• Approval workflow requirements
• Production release criteria

With JSON Schema

python3 skills/artifact.validate/artifact_validate.py \
  my-business-case.yaml \
  --schema-path schemas/artifacts/business-case-schema.json

Save Validation Report

python3 skills/artifact.validate/artifact_validate.py \
  my-artifact.yaml \
  --output validation-report.yaml

Validation Checks

1. Syntax Validation (30% weight)

YAML Artifacts:

• Valid YAML syntax
• Proper indentation
• No duplicate keys
• Valid data types

Markdown Artifacts:

• At least one heading
• Document control section
• Proper markdown structure

Score:

• ✅ Valid: 100 points
• ❌ Invalid: 0 points

2. Metadata Completeness (25% weight)

Required Fields:

• version - Semantic version (e.g., 1.0.0)
• created - Creation date (YYYY-MM-DD)
• author - Author name or team
• status - Draft | Review | Approved | Published

Recommended Fields:

• lastModified - Last modification date
• classification - Public | Internal | Confidential | Restricted
• documentOwner - Owning role or person
• approvers - Approval workflow
• relatedDocuments - Dependencies and references

Scoring:

• Missing required field: -25 points each
• Missing recommended field: -10 points each
• TODO placeholder in field: -10 points

3. Required Sections (25% weight)

YAML Artifacts:

• metadata section required
• content section expected (unless schema-only artifact)
• Empty content fields detected

Scoring:

• Missing required section: -30 points each
• Empty content warning: -15 points each

4. TODO Markers (20% weight)

Detects placeholder content:

• TODO markers
• TODO: comments
• Empty required fields
• Template placeholders

Scoring:

• Each TODO marker: -5 points
• Score floor: 0 (cannot go negative)

Quality Score Interpretation

Score	Rating	Meaning	Recommendation
90-100	Excellent	Ready for approval	Minimal polish
70-89	Good	Minor improvements	Review recommendations
50-69	Fair	Needs refinement	Address key issues
< 50	Poor	Significant work needed	Major revision required

Validation Report Structure

success: true
validation_results:
  artifact_path: /path/to/artifact.yaml
  artifact_type: business-case
  file_format: yaml
  file_size: 2351
  validated_at: 2025-10-25T19:30:00

  syntax:
    valid: true
    error: null

  metadata:
    complete: false
    score: 90
    issues: []
    warnings:
      - "Field 'documentOwner' contains TODO marker"

  sections:
    valid: true
    score: 100
    issues: []
    warnings: []

  todos:
    - "Line 10: author: TODO"
    - "Line 15: documentOwner: TODO"
    # ... more TODOs

  quality_score: 84
  recommendations:
    - "🟡 Complete 1 recommended metadata field(s)"
    - "🔴 Replace 13 TODO markers with actual content"
    - "🟢 Artifact is good - minor improvements recommended"

is_valid: true
quality_score: 84

Command-Line Options

Option	Type	Default	Description
artifact_path	string	required	Path to artifact file
--artifact-type	string	auto-detect	Artifact type override
--strict	flag	false	Treat warnings as errors
--schema-path	string	none	Path to JSON schema
--output	string	none	Save report to file

Exit Codes

• 0: Validation passed (artifact is valid)
• 1: Validation failed (artifact has critical issues)

In strict mode, warnings also cause exit code 1.

Integration Examples

CI/CD Pipeline (GitHub Actions)

name: Validate Artifacts

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Validate artifacts
        run: |
          python3 skills/artifact.validate/artifact_validate.py \
            artifacts/*.yaml \
            --strict

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Validate all modified YAML artifacts
git diff --cached --name-only | grep '\.yaml$' | while read file; do
  python3 skills/artifact.validate/artifact_validate.py "$file" --strict
  if [ $? -ne 0 ]; then
    echo "❌ Validation failed for $file"
    exit 1
  fi
done

Makefile Target

.PHONY: validate
validate:
	@echo "Validating artifacts..."
	@find artifacts -name "*.yaml" -exec \
	  python3 skills/artifact.validate/artifact_validate.py {} \;

Artifact Type Detection

The skill automatically detects artifact type using:

1. Filename match: Direct match with registry (e.g., business-case.yaml)
2. Partial match: Artifact type found in filename (e.g., portal-business-case.yaml → business-case)
3. Metadata: artifactType field in YAML metadata
4. Manual override: --artifact-type parameter

Error Handling

File Not Found

Error: Artifact file not found: /path/to/artifact.yaml

Unsupported Format

Error: Unsupported file format: .txt. Expected yaml, yml, or md

YAML Syntax Error

Syntax Validation:
  ❌ YAML syntax error: while parsing a block mapping
     in "<unicode string>", line 3, column 1
     expected <block end>, but found '<block mapping start>'

Performance

• Validation time: < 100ms per artifact
• Memory usage: < 10MB
• Scalability: Can validate 1000+ artifacts in batch

Dependencies

• Python 3.7+
• yaml (PyYAML) - YAML parsing
• artifact.define skill - Artifact registry

Status

Active - Phase 2 implementation complete

Tags

artifacts, validation, quality, schema, tier2, phase2

Version History

• 0.1.0 (2025-10-25): Initial implementation
  • Syntax validation (YAML/Markdown)
  • Metadata completeness checking
  • Required section verification
  • TODO marker detection
  • Quality scoring
  • Strict mode
  • JSON schema support (framework)

See Also

• artifact.review - AI-powered content quality review
• artifact.create - Generate artifacts from templates
• schemas/artifacts/ - JSON schema library
• docs/ARTIFACT_USAGE_GUIDE.md - Complete usage guide