hierarchy-validation

name

hierarchy-validation

description

**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
• [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

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

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.

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.

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

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 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.