This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

← Home

Standards Compliance Workflow

Workflow: standards-compliance.yml
Status: Active | Version: 04.00.04 | Last Updated: 2026-02-21

Overview

The Standards Compliance workflow is a comprehensive validation system that ensures repositories meet moko-platform requirements across multiple dimensions including structure, documentation quality, coding standards, security, and maintainability.

Purpose

Enforce Standards: Automatically validate compliance with moko-platform policies
Quality Assurance: Ensure consistent quality across all organization repositories
Early Detection: Catch compliance issues before merge
Actionable Feedback: Provide clear remediation steps for any violations
Comprehensive Reporting: Generate detailed compliance reports with scores

Workflow Triggers

on:
  push:
    branches:
      - main
      - dev/**
      - rc/**
  pull_request:
    branches:
      - main
      - dev/**
      - rc/**
  workflow_dispatch:

Runs on:

Every push to main, dev/, or rc/ branches
Every pull request targeting main, dev/, or rc/
Manual trigger via Gitea Actions UI

Validation Areas

The workflow performs 10 comprehensive validation checks organized into two categories:

Critical Checks (Must Pass)

These checks are blocking - the workflow will fail if any critical check fails:

Check	Description	Validator	Priority
📁 Repository Structure	Validates required directories and files exist	Built-in shell	🔴 Critical
📚 Documentation Quality	Analyzes README, checks documentation completeness	Built-in shell	🔴 Critical
💻 Coding Standards	Runs language-specific linters (Python, PHP, YAML)	yamllint, black, pylint, phpcs	🔴 Critical
⚖️ License Compliance	Validates license file and SPDX identifiers	Built-in shell	🔴 Critical
🧹 Git Repository Hygiene	Checks commit messages, branch naming, .gitignore	Built-in shell	🔴 Critical
⚙️ Workflow Configuration	Validates Gitea Actions workflow files	actionlint, custom checks	🔴 Critical
🔢 Version Consistency	Ensures all version numbers match across repository	check_version_consistency.php	🔴 Critical
🔐 Script Integrity	Validates SHA-256 hashes of critical scripts	validate_script_registry.py	🔴 Critical

Informational Checks (Non-Blocking)

These checks provide recommendations but don't fail the workflow:

Check	Description	Validator	Priority
🏢 Enterprise Readiness	Assesses enterprise-grade features and patterns	check_enterprise_readiness.php	ℹ️ Info
🏥 Repository Health	Evaluates overall repository quality metrics	check_repo_health.php	ℹ️ Info

Detailed Check Descriptions

1. Repository Structure Validation

What it checks:

Required directories: docs/, scripts/, .github/
Required files: README.md, LICENSE, CONTRIBUTING.md, SECURITY.md, CHANGELOG.md, .editorconfig
File size and completeness validation

Compliance Requirements:

All required directories must exist
All required files must be present
README must be at least 500 bytes
LICENSE must be at least 100 bytes

Remediation:

# Create missing directories
mkdir -p docs scripts .gitea/workflows

# Create required files from templates
cp templates/docs/required/README.md ./
cp templates/docs/required/CONTRIBUTING.md ./
cp templates/docs/required/SECURITY.md ./

2. Documentation Quality Check

What it checks:

README.md metrics (size, lines, words, headings, links, code blocks)
Documentation completeness
Content quality indicators

Compliance Requirements:

README minimum 500 bytes, 20 lines, 100 words
At least 3 headings for structure
Include links and code examples

Scoring:

Size: 500+ bytes (good), <500 (warning), >50KB (warning - too long)
Headings: 3+ (good), <3 (warning)
Links: 1+ (good), 0 (info - consider adding)
Code blocks: 1+ (good), 0 (info - consider adding)

3. Coding Standards Validation

What it checks:

YAML files: Validates syntax and formatting with yamllint
Python files: Code formatting with black, linting with pylint
PHP files: Coding standards with phpcs (PSR-12)

Compliance Requirements:

All YAML files must be valid and properly formatted
Python code must follow Black formatting
PHP code must follow PSR-12 standards

Remediation:

# Fix YAML formatting
yamllint --format auto .gitea/workflows/*.yml

# Fix Python formatting
black scripts/**/*.py

# Fix PHP code style
phpcs --standard=PSR12 src/

4. License Compliance

What it checks:

LICENSE file exists
File headers contain copyright and SPDX identifiers
Consistent licensing across repository

Compliance Requirements:

LICENSE file present at repository root
All source files include copyright header
SPDX-License-Identifier present in headers

Example Header:

<?php
// Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
// SPDX-License-Identifier: GPL-3.0-or-later

5. Git Repository Hygiene

What it checks:

Commit message format
Branch naming conventions
.gitignore completeness
No sensitive files in repository

Compliance Requirements:

Conventional commit messages
Branch names follow pattern: feature/*, bugfix/*, hotfix/*, release/*
Comprehensive .gitignore file

6. Workflow Configuration Validation

What it checks:

Valid YAML syntax in workflow files
Required workflows present
CodeQL configuration if applicable
Action version pinning for security

Compliance Requirements:

All workflows have valid YAML syntax
Actions pinned to commit hashes for security
Proper permissions configured

7. Version Consistency Check ⭐ NEW

What it checks:

All version references match the canonical version in composer.json
Checks 39+ files including:
- Documentation (README.md, CHANGELOG.md, CONTRIBUTING.md)
- Workflows (.gitea/workflows/*.yml)
- PHP source files (src/**/*.php)
- Configuration files

Compliance Requirements:

Single source of truth: version in composer.json
All references must match exactly
No version drift across repository

Validator: api/validate/check_version_consistency.php

Remediation:

# Check current status
php api/validate/check_version_consistency.php --verbose

# Update all version references (if mismatches found)
# Manually update files or use bulk search/replace

8. Script Integrity Validation ⭐ NEW

What it checks:

SHA-256 hashes of critical scripts match registry
No unauthorized modifications to security-critical scripts
Registry file (scripts/.script-registry.json) is up-to-date

Compliance Requirements:

All scripts in registry must have valid SHA-256 hashes
Critical priority scripts cannot have mismatches
Changes to scripts must update registry

Validator: api/maintenance/validate_script_registry.py

Remediation:

# Validate current hashes
python3 api/maintenance/validate_script_registry.py --priority critical

# Update registry after legitimate changes
python3 api/maintenance/generate_script_registry.py --update

# Or use auto-update workflow
# .gitea/workflows/auto-update-sha.yml

9. Enterprise Readiness Check ⭐ NEW (Informational)

What it checks:

Enterprise-grade features implementation
Security best practices
Scalability patterns
Error handling and logging
Transaction management
API design patterns

Assessment Areas:

Architecture patterns
Error recovery mechanisms
Monitoring and observability
Documentation completeness
Test coverage
Security controls

Validator: api/validate/check_enterprise_readiness.php

Note: This check is informational only and does not block merges. It provides recommendations for improving enterprise readiness.

10. Repository Health Check ⭐ NEW (Informational)

What it checks:

Code quality metrics
Technical debt indicators
Dependency health
Documentation coverage
Test coverage
Issue/PR activity

Health Metrics:

File structure organization
Code duplication
Dependency freshness
Security vulnerabilities
Community engagement

Validator: api/validate/check_repo_health.php

Note: This check is informational only and does not block merges. It provides insights for continuous improvement.

Compliance Scoring

The workflow calculates a compliance percentage based on critical checks:

Compliance % = (Critical Checks Passed / Total Critical Checks) × 100

Score Interpretation

Score	Status	Description
100%	✅ COMPLIANT	All critical checks passed - repository fully compliant
80-99%	⚠️ MOSTLY COMPLIANT	Most checks passed - minor issues to address
50-79%	⚠️ PARTIALLY COMPLIANT	Significant issues - requires attention
0-49%	❌ NON-COMPLIANT	Major compliance violations - immediate action required

Example Output

## ✅ Overall Status: COMPLIANT (100%)

**Critical Checks:** 8/8 passed
**Total Checks:** 10/10 passed
**Informational:** 0 warning(s)

████████████████████ 100%

## Validation Results

| Area                        | Status  | Result     | Priority    |
|-----------------------------|---------|------------|-------------|
| 📁 Repository Structure     | ✅ Pass | Compliant  | -           |
| 📚 Documentation Quality    | ✅ Pass | Compliant  | -           |
| 💻 Coding Standards         | ✅ Pass | Compliant  | -           |
| ⚖️ License Compliance       | ✅ Pass | Compliant  | -           |
| 🧹 Git Repository Hygiene   | ✅ Pass | Compliant  | -           |
| ⚙️ Workflow Configuration   | ✅ Pass | Compliant  | -           |
| 🔢 Version Consistency      | ✅ Pass | All versions match | -    |
| 🔐 Script Integrity         | ✅ Pass | SHA hashes validated | -  |
| 🏢 Enterprise Readiness     | ✅ Pass | Ready for enterprise | ℹ️ Info |
| 🏥 Repository Health        | ✅ Pass | Health check passed  | ℹ️ Info |

Usage Examples

Running Manually

# Trigger workflow manually via Gitea Actions UI
# Go to: Actions → Standards Compliance → Run workflow

# Or use GitHub CLI
gh workflow run standards-compliance.yml

Local Validation

Run individual validators locally before pushing:

# Check version consistency
php api/validate/check_version_consistency.php --verbose

# Validate script integrity
python3 api/maintenance/validate_script_registry.py --priority critical --verbose

# Check enterprise readiness
php api/validate/check_enterprise_readiness.php --verbose

# Check repository health
php api/validate/check_repo_health.php --verbose

# Lint YAML files
yamllint .gitea/workflows/*.yml

# Format Python code
black --check scripts/**/*.py

# Check PHP code style
phpcs --standard=PSR12 src/

Fixing Common Issues

Version Mismatches

# 1. Identify current version
grep '"version"' composer.json

# 2. Find mismatches
php api/validate/check_version_consistency.php

# 3. Update all references to match
# Use sed or manually update files listed in output

Script Integrity Violations

# If changes are legitimate:
python3 api/maintenance/generate_script_registry.py --update

# If changes are NOT authorized:
git checkout HEAD -- scripts/

Coding Standard Violations

# Auto-fix Python formatting
black scripts/**/*.py

# Auto-fix PHP code style
phpcbf --standard=PSR12 src/

# Fix YAML issues
# Manual fixes required based on yamllint output

Integration with Pull Requests

The workflow automatically:

Runs on every PR to main, dev/, or rc/ branches
Posts results in the PR checks section
Provides detailed summary in the workflow run
Blocks merge if critical checks fail
Offers remediation steps for any violations

PR Status Checks

Check Result	PR Status	Merge Allowed
All critical checks pass	✅ Success	Yes
Any critical check fails	❌ Failure	No (blocked)
Only informational warnings	✅ Success	Yes

Workflow Architecture

┌─────────────────────────────────────────────────────────────┐
│              PARALLEL VALIDATION CHECKS                      │
└─────────────────────────────────────────────────────────────┘
     │
     ├─────────────┬──────────────┬──────────────┬────────────┐
     ▼             ▼              ▼              ▼            ▼
┌─────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐
│Repository  │File Header  │Code Style│  │  Docs   │  │ License  │
│Structure│  │ Validation│  │  Check   │  │  Check  │  │  Check   │
└─────────┘  └──────────┘  └──────────┘  └─────────┘  └──────────┘
     │             │              │              │            │
     ├─────────────┼──────────────┼──────────────┼────────────┤
     ▼             ▼              ▼              ▼            ▼
┌─────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐
│  Git    │  │ Workflow │  │ Version  │  │ Script  │  │Enterprise│
│ Hygiene │  │  Config  │  │Consistency│  │Integrity│  │Readiness │
└─────────┘  └──────────┘  └──────────┘  └─────────┘  └──────────┘
     │             │              │              │            │
     └─────────────┴──────────────┴──────────────┴────────────┘
                                     │
                                     ▼
                           ┌──────────────────┐
                           │  All Checks Pass?│
                           └──────────────────┘
                              │            │
                          YES │            │ NO
                              ▼            ▼
                       ┌──────────┐  ┌──────────────┐
                       │  SUCCESS │  │ CREATE ISSUE │
                       │  Summary │  │ with Failure │
                       └──────────┘  │   Details    │
                                     └──────────────┘

Customization

Adjusting Severity

To change a critical check to informational (non-blocking):

# In the summary job, change from:
[ "$CHECK_STATUS" = "success" ] && PASSED=$((PASSED + 1)) || FAILED=$((FAILED + 1))

# To:
if [ "$CHECK_STATUS" = "success" ]; then
  PASSED=$((PASSED + 1))
else
  WARNINGS=$((WARNINGS + 1))
fi

Adding Custom Checks

Add a new validation job:

custom-check:
  name: Custom Validation
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@v6
    
    - name: Run Custom Validator
      run: |
        ./scripts/custom-validator.sh

Then add it to the summary needs array.

Skipping Checks

To skip a check temporarily, add to job:

if: false  # Skip this check

Or make conditional:

if: ${{ github.event_name != 'pull_request' }}  # Skip on PRs

Troubleshooting

Workflow Fails Unexpectedly

Check:

Review workflow run logs in Gitea Actions
Look for specific error messages in failed jobs
Check if required scripts exist (new checks depend on PHP/Python scripts)

Common Issues:

Missing validator scripts (version/enterprise/health checks)
PHP/Python not available in runner
Permissions issues with files

Version Consistency Always Fails

Cause: Multiple version references across repository don't match

Fix:

Identify canonical version: grep '"version"' composer.json
Find mismatches: php api/validate/check_version_consistency.php
Update all references to match canonical version

Script Integrity Violations

Legitimate Changes:

# Update registry after modifying scripts
python3 api/maintenance/generate_script_registry.py --update
git add scripts/.script-registry.json
git commit -m "chore: update script registry"

Unauthorized Changes:

# Restore original scripts
git checkout HEAD -- scripts/

Changelog

v04.00.04 (2026-02-21)

Added:

✨ Version Consistency Check - Validates all version numbers match
✨ Script Integrity Validation - Verifies SHA-256 hashes
✨ Enterprise Readiness Check - Assesses enterprise patterns (informational)
✨ Repository Health Check - Evaluates overall quality (informational)

Changed:

📊 Enhanced compliance scoring with critical vs informational distinction
📊 Improved summary reporting with detailed breakdowns
📊 Total validation checks increased from 6 to 10

Fixed:

🐛 Compliance percentage now correctly calculates based on critical checks only

v04.00.04 (2026-01-07)

Added:

Initial comprehensive standards compliance workflow
Repository structure validation
Documentation quality checks
Coding standards enforcement
License compliance validation
Git hygiene checks
Workflow configuration validation

Maintained by: moko-platform Team
Last Review: 2026-02-21
Next Review: 2026-03-21

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version

Standards Compliance Workflow

Overview

Purpose

Workflow Triggers

Validation Areas

Critical Checks (Must Pass)

Informational Checks (Non-Blocking)

Detailed Check Descriptions

1. Repository Structure Validation

2. Documentation Quality Check

3. Coding Standards Validation

4. License Compliance

5. Git Repository Hygiene

6. Workflow Configuration Validation

7. Version Consistency Check ⭐ NEW

8. Script Integrity Validation ⭐ NEW

9. Enterprise Readiness Check ⭐ NEW (Informational)

10. Repository Health Check ⭐ NEW (Informational)

Compliance Scoring

Score Interpretation

Example Output

Usage Examples

Running Manually

Local Validation

Fixing Common Issues

Version Mismatches

Script Integrity Violations

Coding Standard Violations

Integration with Pull Requests

PR Status Checks

Workflow Architecture

Customization

Adjusting Severity

Adding Custom Checks

Skipping Checks

Troubleshooting

Workflow Fails Unexpectedly

Version Consistency Always Fails

Script Integrity Violations

Related Documentation

Changelog

v04.00.04 (2026-02-21)

v04.00.04 (2026-01-07)

Maintained by: moko-platform Team Last Review: 2026-02-21 Next Review: 2026-03-21

Maintained by: moko-platform Team
Last Review: 2026-02-21
Next Review: 2026-03-21