$3b
45:T431e,
Validate structural integrity and cross-level consistency across a process hierarchy tree.
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.
[process-folder]/ — validates only that folder and its direct parent links[process-folder]/[NN]-[Name]Boundary/ — validates only that branchorgModel/01 - Skill Development Process/) — validates all levels[process-folder]/hierarchy-metadata.json — accelerates traversal; generated by hierarchy-management--mode full | incremental (default: full)--fix[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| 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. |
| 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. |
| 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). |
full (start from root) or incremental (start from the specified branch folder).collaboration.md and main.md files.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).{ folder → parent_folder, children: [child_folders] }.hierarchy-metadata.json from the root if available (speeds up step 3 traversal).For each parent collaboration.md that has one or more child sub-folders:
collaboration.md and extract all participants whose stereotype (from the %% Stereotypes: comment) is control.Boundary suffix, then compare case-insensitively with PascalCase normalization.control-type participant is found in the parent for a given sub-folder.collaboration.md.box … end blocks.actor-type participant exists outside all boxes.label of the external actor found in HV-2 with the label (or name) of the decomposed control in the parent.box … end block in the child collaboration.md:
@{ "type": "..." } annotation.boundary.box … end blocks in the child collaboration.md, excluding the boundary-type entry-point participant.collaboration.md.main.md, extract the **Parent Process**: [text](relative-path) link.main.md, read the ## Sub-Processes table.[text](path), resolve the relative path.main.md: **Breadcrumb**: [Ancestor1](path) › … › Current.collaboration.md for lines matching %% [Dd]ecompos(ed|ition):\s*\S+\s*→\s*(\S+).hierarchy-index.md exists at the root, parse all folder paths listed in the ## Full Hierarchy Tree table.^\d{2}-[A-Za-z][A-Za-z0-9]*Boundary$ to each sub-process folder name.collaboration.md and main.md exist.**Level**: [N] from each main.md.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
--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.
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.
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": []
}
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.
When validating a single branch (--mode incremental):
[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.
| 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 |
hierarchy-management creates or updates hierarchy levels to confirm structural integrity.--mode incremental for fast post-edit checks on a single branch.edps-compliance — resolve all hierarchy-validation ERRORs before running full EDPS compliance.change-management for tracking.--fix to automatically correct navigation and metadata issues before generating a project-status-reporting health snapshot.