**Authoritative structural integrity checker for the EDPS skill suite.** Validate hierarchy consistency across all levels of an EDPS process hierarchy. Checks cross-level participant type consistency (control-type participants at Level N must appear as external actors at Level N+1), boundary rule compliance at every level, cross-reference link integrity through the full tree, and participant label/type propagation. All file/link integrity and structural naming rules for EDPS hierarchies are exclusively owned by this skill; other skills (e.g., edps-compliance) delegate these checks to hierarchy-validation via a mandatory pre-condition gate rather than re-implementing them. Supports both full-tree validation and incremental single-branch validation. Generates per-level, per-rule validation reports with severity classification and auto-fix suggestions. Use when a user wants to validate hierarchy structural integrity, check cross-level type consistency, verify navigation link integrity, or run a targeted validati
**Authoritative structural integrity checker for the EDPS skill suite.** Validate hierarchy consistency across all levels of an EDPS process hierarchy. Checks cross-level participant type consistency (control-type participants at Level N must appear as external actors at Level N+1), boundary rule compliance at every level, cross-reference link integrity through the full tree, and participant label/type propagation. All file/link integrity and structural naming rules for EDPS hierarchies are exclusively owned by this skill; other skills (e.g., edps-compliance) delegate these checks to hierarchy-validation via a mandatory pre-condition gate rather than re-implementing them. Supports both full-tree validation and incremental single-branch validation. Generates per-level, per-rule validation reports with severity classification and auto-fix suggestions. Use when a user wants to validate hierarchy structural integrity, check cross-level type consistency, verify navigation link integrity, or run a targeted validation on a specific branch of the hierarchy.
Hierarchy Validation
Validate structural integrity and cross-level consistency across a process hierarchy tree.
Intent
Authoritatively validate structural integrity, cross-level type consistency, navigation link integrity, and naming convention compliance across the full EDPS process hierarchy. All file/link integrity checks are exclusively owned here; other skills (edps-compliance, documentation-automation) delegate these checks via a pre-condition gate rather than re-implementing them.
Inputs
Target scope: one of:
Single level: [process-folder]/ — validates only that folder and its direct parent links
Sub-tree (incremental): [process-folder]/[NN]-[Name]Boundary/ — validates only that branch
Full hierarchy: root process folder (e.g., orgModel/01 - Skill Development Process/) — validates all levels
Optional: [process-folder]/hierarchy-metadata.json — accelerates traversal; generated by hierarchy-management
Optional: --mode full | incremental (default: full)
Optional: --fix flag — apply auto-fix for common issues automatically
Outputs
[root-folder]/artifacts/Testing/hierarchy-validation-report.md — human-readable report with per-level and per-rule results
Console summary: total checks, pass/fail/warning counts, and next recommended action
Validation Rule Catalogue
Group HV — Cross-Level Type Consistency Rules
ID
Name
Severity
Description
HV-1
Decomposed-Participant Is Control
ERROR
Every sub-process folder must correspond to a control-type participant in the parent collaboration.md. Non-control participants may not be decomposed.
HV-2
Parent Actor Appearance
ERROR
The participant decomposed at Level N must appear as an actor-type participant outside all box blocks in the Level N+1 collaboration.md.
HV-3
Actor Label Consistency
WARNING
The label annotation of the external actor in the child collaboration should match (or be a recognizable sub-string of) the decomposed participant's label in the parent.
HV-4
Entry-Point Type Integrity
ERROR
The first participant declared inside the box at Level N+1 must be boundary-type. This is the required entry point for the sub-process.
HV-5
No Internal Leakage
ERROR
Child-level internal participants (controls, entities, non-entry boundaries) must not appear by name in the parent collaboration.md.
Group HX — Cross-Reference Integrity Rules
ID
Name
Severity
Description
HX-1
Parent Link Resolves
ERROR
**Parent Process** link in each sub-process main.md must resolve to an existing file.
HX-2
Child Links Resolves
ERROR
Every entry in the ## Sub-Processes table of a main.md must resolve to an existing file.
HX-3
Breadcrumb Path Integrity
WARNING
Every link in the breadcrumb trail must resolve to an existing main.md.
HX-4
Decomposition Comment Matches Folder
WARNING
Each %% Decomposition: or %% decomposed: comment in a collaboration.md must reference an existing sub-folder.
HX-5
Hierarchy Index Currency
WARNING
hierarchy-index.md at the root (if present) must list all sub-process folders at every level. Missing entries generate a warning.
Group HN — Naming and Structure Rules
ID
Name
Severity
Description
HN-1
Folder Name Convention
ERROR
Sub-process folders must match ^\d{2}-[A-Za-z][A-Za-z0-9]*Boundary$.
HN-2
Required Files Present
ERROR
Each sub-process folder must contain collaboration.md and main.md. process.md and domain-model.md are recommended but not required.
HN-3
Ordinal Uniqueness
ERROR
No two sibling sub-process folders under the same parent may share the same ordinal prefix.
HN-4
Level Number Consistency
WARNING
The **Level**: [N] field in each main.md must match the actual folder depth from the root (root = Level 0).
Workflow
Step 1 — Discover Scope
Determine mode: full (start from root) or incremental (start from the specified branch folder).
Walk the folder tree collecting all collaboration.md and main.md files.
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).
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.
Rule
Auto-Fix
HX-1
If the parent main.md exists at the expected depth, reconstruct the relative path and update main.md
HX-2
If a sub-process folder exists but is listed with a wrong relative path, correct the path in the parent main.md
HX-3
Rebuild the breadcrumb from the parent map computed in Step 1 and update main.md
HX-4
If the sub-folder exists under a different ordinal, update the comment path; otherwise remove the stale comment
HX-5
Re-generate the ## Full Hierarchy Tree table in hierarchy-index.md using the filesystem walk
HN-4
Update the **Level**: [N] field in main.md to the computed depth value
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.
{"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 Priority1.**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):
Start from the specified sub-folder as the root of the scan.
Walk downward through all descendant sub-folders.
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.
Skip all sibling branches and ancestor levels beyond the direct parent.
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
Rule
Common Fix
HV-1
Add a control-type participant matching the sub-folder name to the parent collaboration.md, or delete the orphaned sub-folder after confirming it is unused
HV-2
Add the parent participant as an external actor (outside all box blocks) in the child collaboration.md and list it as actor in the %% Stereotypes: comment
HV-3
Align the label of the external actor to match the decomposed participant's label in the parent diagram
HV-4
Reorder the first message inside the box so the first recipient is a boundary-type participant
HV-5
Remove child-level participant declarations from the parent diagram; reference the boundary as a single decomposed control participant
HX-1
Re-add **Parent Process**: [[Name]](../main.md) to the sub-process main.md and correct the relative path
HX-2
Update the stale link in the parent ## Sub-Processes table to the correct relative path
HX-3
Rebuild the breadcrumb using hierarchy-management cross-reference rebuild, or run --fix
HX-4
Update the %% decomposed: comment path to the current sub-folder name, or remove if the decomposition was rolled back
HX-5
Run hierarchy-management to regenerate hierarchy-index.md, or run --fix
HN-1
Rename the folder to conform to ^\d{2}-[A-Za-z][A-Za-z0-9]*Boundary$ and update all references
HN-2
Create the missing collaboration.md or main.md using hierarchy-management templates
HN-3
Renumber sub-folders to eliminate ordinal conflicts (assign unique two-digit prefixes in order) and update all references
HN-4
Update **Level**: [N] in main.md to the correct depth value, or run --fix
Integration with Other Skills
Run afterhierarchy-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.
