Hierarchy Validation

Outputs

• [root-folder]/artifacts/Testing/hierarchy-validation-report.md — human-readable report with per-level and per-rule results
• [root-folder]/artifacts/Testing/hierarchy-validation-report.json — machine-readable results
• Console summary: total checks, pass/fail/warning counts, and next recommended action

Validation Rule Catalogue

Group HV — Cross-Level Type Consistency Rules

Group HX — Cross-Reference Integrity Rules

Group HN — Naming and Structure Rules

Workflow

Step 1 — Discover Scope

1. Determine mode: full (start from root) or incremental (start from the specified branch folder).
2. Walk the folder tree collecting all collaboration.md and main.md files.
3. For each collaboration.md, record its hierarchy level by counting folder depth from the root process folder (root = Level 0; each [NN]-[Name]Boundary/ sub-folder adds 1).
4. Build a parent-child map: { folder → parent_folder, children: [child_folders] }.
5. Load hierarchy-metadata.json from the root if available (speeds up step 3 traversal).

Step 2 — Apply Group HV Rules (per parent → child pair)

For each parent collaboration.md that has one or more child sub-folders:

HV-1 Check

• Read the parent collaboration.md and extract all participants whose stereotype (from the %% Stereotypes: comment) is control.
• For each child sub-folder, derive the expected participant name: strip the two-digit ordinal prefix and the Boundary suffix, then compare case-insensitively with PascalCase normalization.
• FAIL if no matching control-type participant is found in the parent for a given sub-folder.

HV-2 Check

• Read the child collaboration.md.
• Identify participants declared outside all box … end blocks.
• Find any participant whose name (or label) matches the parent's decomposed control participant name.
• FAIL if no such actor-type participant exists outside all boxes.

HV-3 Check

• Compare the label of the external actor found in HV-2 with the label (or name) of the decomposed control in the parent.
• WARN if the strings have less than 50 % character overlap (case-insensitive, ignoring common suffix words like "Boundary", "Service", "Manager").

HV-4 Check

• Within each box … end block in the child collaboration.md:
  • Identify the participant that receives the first inbound message from the external actor.
  • Check its @{ "type": "..." } annotation.
• FAIL if the first recipient's type is not boundary.

HV-5 Check

• Collect all participant names declared inside box … end blocks in the child collaboration.md, excluding the boundary-type entry-point participant.
• Check whether any of these names appear as participant declarations in the parent collaboration.md.
• FAIL for each leaking participant name found in the parent.

Step 3 — Apply Group HX Rules (per folder)

HX-1 Check

• From each sub-process main.md, extract the **Parent Process**: [text](relative-path) link.
• Resolve the relative path from the file's directory.
• FAIL if the target file does not exist.

HX-2 Check

• From each main.md, read the ## Sub-Processes table.
• For each markdown link [text](path), resolve the relative path.
• FAIL for each link that does not resolve to an existing file.

HX-3 Check

• Parse the breadcrumb line from each main.md: **Breadcrumb**: [Ancestor1](path) › … › Current.
• Resolve each linked path.
• WARN for any broken link.

HX-4 Check

• Scan each collaboration.md for lines matching %% [Dd]ecompos(ed|ition):\s*\S+\s*→\s*(\S+).
• Extract the target path from each match.
• Resolve relative to the file's directory.
• WARN if the referenced sub-folder does not exist.

HX-5 Check

• If hierarchy-index.md exists at the root, parse all folder paths listed in the ## Full Hierarchy Tree table.
• Walk the actual filesystem and compare.
• WARN for each sub-process folder not listed in the index.

Step 4 — Apply Group HN Rules (per folder)

HN-1 Check

• Apply regex ^\d{2}-[A-Za-z][A-Za-z0-9]*Boundary$ to each sub-process folder name.
• FAIL on any non-conforming name.

HN-2 Check

• For each sub-process folder, verify collaboration.md and main.md exist.
• FAIL for each missing required file.

HN-3 Check

• Group sub-process folders by parent.
• Within each sibling group, extract the two-digit ordinal prefix.
• FAIL if two siblings share the same ordinal.

HN-4 Check

• Read **Level**: [N] from each main.md.
• Compare against the computed depth value from Step 1.
• WARN if they differ.

Step 5 — Score and Aggregate

validation_score = (passed_checks / total_checks) × 100
  where total_checks = count of rules with status PASS or FAIL (not SKIPPED)

severity_counts:
  errors   = count of FAIL on ERROR-severity rules
  warnings = count of FAIL on WARNING-severity rules

overall_status (first match wins):
  VALID            → errors = 0  AND  validation_score ≥ 90
  MOSTLY_VALID     → errors = 0  AND  validation_score ≥ 70
  INVALID          → errors > 3
  NEEDS_ATTENTION  → all other cases

Step 6 — Auto-Fix Pass (when --fix is specified)

Apply the following auto-fixes in order before generating the report. Log each fix applied.

Fixes for structural ERROR-severity rules (HV-*, HN-1/2/3) are not auto-applied — they require human review. Report them with explicit remediation instructions instead. HX-1 and HX-2 auto-fixes (relative path reconstruction only) are safe to apply automatically because they do not alter hierarchy structure.

Step 7 — Generate Reports

Console Summary

Hierarchy Validation — [scope path]
  Mode:     [full | incremental]
  Levels:   [count]
  Folders:  [count]

  Overall:  [VALID | MOSTLY_VALID | NEEDS_ATTENTION | INVALID]
  Score:    [score]%  ([passed]/[total] checks)
  Errors:   [count]
  Warnings: [count]
  Auto-fixed: [count] (if --fix was used)

[If errors > 0]
  ❌ Fix required before hierarchy is structurally sound.
[If errors = 0 AND warnings > 0]
  ⚠  Warnings present — review recommended.
[If errors = 0 AND warnings = 0]
  ✅ Hierarchy is structurally valid.

JSON Report (hierarchy-validation-report.json)

{
  "report_metadata": {
    "generated": "ISO8601 timestamp",
    "scope": "path to validated folder",
    "mode": "full | incremental",
    "schema_version": "1.0"
  },
  "summary": {
    "overall_status": "VALID | MOSTLY_VALID | NEEDS_ATTENTION | INVALID",
    "validation_score": 0.0,
    "total_checks": 0,
    "passed": 0,
    "failed_errors": 0,
    "failed_warnings": 0,
    "auto_fixed": 0,
    "levels_scanned": 0,
    "folders_scanned": 0
  },
  "rule_results": [
    {
      "rule_id": "HV-1",
      "rule_name": "Decomposed-Participant Is Control",
      "group": "HV",
      "severity": "ERROR",
      "status": "PASS | FAIL | SKIPPED",
      "checked_folders": ["path/to/folder"],
      "violations": [
        {
          "folder": "path/to/sub-folder",
          "parent_collaboration": "path/to/parent/collaboration.md",
          "detail": "Sub-folder '01-UserPortalBoundary' found but no control-type participant 'UserPortal' exists in parent diagram",
          "remediation": "Add a control-type participant 'UserPortal' to the parent collaboration diagram, or remove the sub-folder if it was created in error."
        }
      ]
    }
  ],
  "auto_fixes_applied": []
}

Markdown Report (hierarchy-validation-report.md)

# Hierarchy Validation Report

**Generated**: [timestamp]  
**Scope**: [target path]  
**Mode**: [full | incremental]  
**Overall Status**: [VALID ✅ | MOSTLY_VALID ⚠️ | NEEDS_ATTENTION ⚠️ | INVALID ❌]

## Summary

| Metric | Value |
|--------|-------|
| Validation Score | [score]% |
| Total Checks | [n] |
| Passed | [n] |
| Errors (blocking) | [n] |
| Warnings | [n] |
| Levels Scanned | [n] |
| Folders Scanned | [n] |
| Auto-Fixed | [n] |

## Rule Results

### Group HV — Cross-Level Type Consistency

| Rule | Name | Status | Violations |
|------|------|--------|------------|
| HV-1 | Decomposed-Participant Is Control | ✅/❌ | [n] |
| HV-2 | Parent Actor Appearance | ✅/❌ | [n] |
| HV-3 | Actor Label Consistency | ✅/⚠️ | [n] |
| HV-4 | Entry-Point Type Integrity | ✅/❌ | [n] |
| HV-5 | No Internal Leakage | ✅/❌ | [n] |

### Group HX — Cross-Reference Integrity

| Rule | Name | Status | Violations |
|------|------|--------|------------|
| HX-1 | Parent Link Resolves | ✅/❌ | [n] |
| HX-2 | Child Links Resolve | ✅/❌ | [n] |
| HX-3 | Breadcrumb Path Integrity | ✅/⚠️ | [n] |
| HX-4 | Decomposition Comment Matches Folder | ✅/⚠️ | [n] |
| HX-5 | Hierarchy Index Currency | ✅/⚠️ | [n] |

### Group HN — Naming and Structure

| Rule | Name | Status | Violations |
|------|------|--------|------------|
| HN-1 | Folder Name Convention | ✅/❌ | [n] |
| HN-2 | Required Files Present | ✅/❌ | [n] |
| HN-3 | Ordinal Uniqueness | ✅/❌ | [n] |
| HN-4 | Level Number Consistency | ✅/⚠️ | [n] |

## Violations Detail

### ❌ [Rule ID]: [Rule Name]

**Folder**: `path/to/sub-folder`  
**Parent**: `path/to/parent/collaboration.md`  
**Issue**: [specific description]  
**Remediation**: [concrete fix instruction]

---

## Auto-Fixes Applied

[List of fixes, or "No auto-fixes were applied." if --fix was not used or no fixable issues found]

## Remediation Priority

1. **Critical (Errors)**: Resolve all ERROR violations — these indicate structural violations that break hierarchy integrity.
2. **Advisory (Warnings)**: Address WARNING violations to improve navigation and documentation quality.

Incremental Validation

When validating a single branch (--mode incremental):

1. Start from the specified sub-folder as the root of the scan.
2. Walk downward through all descendant sub-folders.
3. Also check the immediate parent (one level up) for HV-1, HV-2, HX-2 rules only — to verify the branch is correctly registered in its parent.
4. Skip all sibling branches and ancestor levels beyond the direct parent.
5. Report scope as [branch-folder] (incremental) in the report header.

This enables fast validation after making changes to a single sub-tree without re-scanning the full hierarchy.

Remediation Reference

Integration with Other Skills

• Run after hierarchy-management creates or updates hierarchy levels to confirm structural integrity.
• Use --mode incremental for fast post-edit checks on a single branch.
• Feeds into edps-compliance — resolve all hierarchy-validation ERRORs before running full EDPS compliance.
• Violations involving missing navigation links can be auto-reported to change-management for tracking.
• Use --fix to automatically correct navigation and metadata issues before generating a project-status-reporting health snapshot.