edps-compliance

name

edps-compliance

description

Validate EDPS (Evolutionary Development Process System) methodology compliance across process hierarchies. Checks evolutionary decomposition patterns, boundary validation rules (VR-1 through VR-4), requirements traceability at each hierarchy level, change history metadata, and incremental model refinement adherence. Generates item-level pass/fail compliance reports in both JSON and Markdown formats. Use when a user wants to validate EDPS compliance, check hierarchy conformance, generate a compliance report, or get remediation suggestions for violations.

EDPS Compliance Checking

Validate that process hierarchy artifacts conform to EDPS methodology principles and generate a scored compliance report with remediation guidance.

Intent

Validate that process hierarchy artifacts conform to EDPS methodology principles. Delegates structural checks to hierarchy-validation (via mandatory pre-condition gate) and boundary validation to diagram-generatecollaboration, then applies evolutionary principle rules (EP-1 through EP-4) to produce a scored compliance report with per-rule remediation guidance.

Inputs

• Target scope: one of:
  • Single diagram: [process-folder]/collaboration.md
  • Full hierarchy: [process-folder]/ (recursively includes all sub-process folders)
  • Entire org model: orgModel/ root
• Optional: [process-folder]/hierarchy-metadata.json — hierarchy metadata produced by hierarchy-management
• Optional: [process-folder]/hierarchy-index.md — cross-reference index produced by hierarchy-management
• Optional: [process-folder]/boundary-validation-report.json — pre-computed VR-1–VR-4 boundary validation results generated by diagram-generatecollaboration. When provided, edps-compliance imports VR results directly from this file instead of re-running the checks. If absent, edps-compliance will automatically invoke diagram-generatecollaboration in boundary-validation mode to produce it.
• Optional: hierarchy-validation-report.json — pre-computed structural validation results generated by hierarchy-validation. When provided and the report's target_scope matches the current target, satisfies the pre-condition gate automatically (see Pre-Conditions). If target_scope does not match, a scope-mismatch warning is issued and manual pre-condition confirmation is required.
• Optional: --mode strict | relaxed (default: relaxed)

Outputs

• [target-folder]/artifacts/Testing/edps-compliance-report.json — machine-readable per-rule results
• [target-folder]/artifacts/Testing/edps-compliance-report.md — human-readable scored report with remediation suggestions
• Console summary: overall score, violation count by severity, and next recommended action

---

Compliance Rule Catalogue

Group A — Boundary Diagram Rules (inherited from diagram-generatecollaboration)

ID	Name	Severity	Description
VR-1	Single External Interface	ERROR	Each box boundary must have exactly one external actor communicating directly into it. Multiple actors must route through a shared gateway.
VR-2	Boundary-First Reception	ERROR	The first message from an external actor inside any box must target a boundary-type participant. Actors must not bypass the entry point.
VR-3	Control-Only Decomposition	ERROR	Only control-type participants are eligible for sub-process decomposition. Decomposing actor, boundary, or entity types is prohibited.
VR-4	Cohesive Responsibility	WARNING	All participants within the same box boundary must share a cohesive functional domain. Mixed concerns trigger a warning.

Group B — Hierarchy Structural Rules

Delegation Note: HR-1 (Parent-Child Link Integrity), HR-3 (Breadcrumb Consistency), HR-4 (Sub-Processes Section Populated), and HR-5 (Folder Naming Convention) have been removed from this skill. Those checks are now exclusively owned by hierarchy-validation (rules HX-1/HX-2, HX-3, HX-5, and HN-1 respectively). The pre-condition gate ensures those checks have already passed before any Group B checks execute here.

ID	Name	Severity	Description
HR-2	Decomposed Participant Exists	ERROR	Every sub-process folder must correspond to a control-type participant that exists in the parent collaboration.md. This is a semantic rule (participant type/name matching) not covered by hierarchy-validation.
HR-6	Metadata Currency	WARNING	hierarchy-metadata.json must exist at the root scope level and its last_updated timestamp must be more recent than any collaboration.md modification time within the hierarchy.

Group C — EDPS Evolutionary Principles

ID	Name	Severity	Description
EP-1	Traceability Presence	ERROR	Each hierarchy level (each collaboration.md) must contain at least one requirements traceability reference — either a [R-NNN] inline citation or a **Source Requirements** frontmatter block.
EP-2	Abstraction Level Separation	ERROR	A collaboration.md must not mix concerns from different hierarchy levels. Participants from child boundary folders must not appear directly in a parent diagram.
EP-3	Evolution Metadata	WARNING	Each main.md should include a **Status** field (Active, Draft, Deprecated) and a **Last Updated** or equivalent timestamp comment (<!-- Last Updated: ... -->).
EP-4	Incremental Refinement Traceability	WARNING	When a sub-process folder exists, the parent collaboration.md should contain a %% decomposed: [ParticipantName] → [NN]-[ParticipantName]Boundary/collaboration.md comment annotating the decomposition.

---

Pre-Conditions

Before executing any compliance checks, hierarchy-validation must have been run on the same target scope and must have exited with an overall status of VALID or MOSTLY_VALID (zero structural ERRORs). If this pre-condition is not satisfied, edps-compliance must halt immediately and return a pre-condition-not-met error without executing any Group A, B, or C checks.

Satisfying the Pre-Condition

There are two ways to satisfy the pre-condition:

1. Pass a report file: Provide hierarchy-validation-report.json as an optional input. edps-compliance will:

   • Validate that the report's target_scope field matches the current run target (resolved to the same canonical path).
   • If the scopes match and overall_status is VALID or MOSTLY_VALID, accept the report and proceed to the workflow steps.
   • If the scopes do not match, issue a scope-mismatch warning and fall back to requiring manual confirmation.

2. Manual confirmation: If no report is provided (or a scope-mismatch occurs), the practitioner must explicitly confirm that hierarchy-validation has been run and passed on the target scope. Without confirmation, edps-compliance emits the pre-condition error and halts.

Pre-Condition Not Met — Error Response

When the pre-condition is not satisfied, emit the following structured error and halt all further processing:

{
  "error": "pre-condition-not-met",
  "missing_pre_condition": "hierarchy-validation PASS (VALID or MOSTLY_VALID) on the same target scope",
  "suggested_command": "Run hierarchy-validation on [target-scope] — resolve all ERRORs until overall_status is VALID or MOSTLY_VALID, then re-run edps-compliance",
  "blocking_issues": [
    "hierarchy-validation has not been run on [target-scope], or its overall_status is INVALID or NEEDS_ATTENTION with errors",
    "— or — hierarchy-validation-report.json was provided but target_scope does not match the current run target"
  ]
}

The overall compliance run status in this case is BLOCKED.

---

Workflow

Group A Delegation Contract: VR-1–VR-4 boundary validation rules are canonically defined and implemented in diagram-generatecollaboration. edps-compliance never reimplements VR check algorithms — it always delegates to diagram-generatecollaboration (Step 2) and maps the results into its own report format. diagram-generatecollaboration is the single authoritative source for all VR rule definitions and check logic.

Step 1 — Discover Scope

1. Determine whether it is a single-file, folder, or full orgModel/ scan.
2. Collect all collaboration.md files within scope.
3. For each file, determine its hierarchy level by counting the depth from the orgModel/ root (Level 0 = root, Level 1 = direct children, etc.).
4. Locate hierarchy-metadata.json at the nearest ancestor level (if present).

Step 2 — Delegate Group A Rules (VR-1–VR-4) to diagram-generatecollaboration

VR-1–VR-4 check algorithms reside exclusively in diagram-generatecollaboration. This step imports their results via delegation, never reimplementing the logic.

For each collaboration.md in scope:

1. Check for pre-existing report: Look for boundary-validation-report.json in the same folder as the target collaboration.md.

   • If found and its validated_at timestamp is more recent than the collaboration.md modification time (or the most recent <!-- Last Updated: --> comment in it), proceed to sub-step 3 (map results).
   • If found but stale (report older than the diagram), proceed to sub-step 2 (re-invoke).
   • If not found, proceed to sub-step 2 (invoke).

2. Invoke diagram-generatecollaboration boundary-validation mode: Run diagram-generatecollaboration with --mode boundary-validation-only targeting the collaboration.md. Capture the emitted boundary_validation_report block as boundary-validation-report.json in the same folder.

   • This step is idempotent: if a report already exists from a prior run in the same session, do not overwrite it — import it as-is.
   • If invocation fails (e.g., the file is malformed or the skill is unavailable), mark VR-1–VR-4 as SKIPPED with reason delegation-failed and continue to Step 3. Do not abort the full compliance check. Output console notice: Group A (VR-1–VR-4): SKIPPED — delegation to diagram-generatecollaboration failed.

3. Map VR results into edps-compliance rule result format: For each rule entry in boundary_validation_report.rule_results:

   • rule_id ← rule field (e.g., "VR-1")
   • rule_name ← rule_name field (e.g., "single-external-interface")
   • group ← "A"
   • severity ← map "error" → "ERROR", "warning" → "WARNING"
   • status ← map "PASS" → "PASS", "FAIL" / "ERROR" → "FAIL", "WARNING" (rule-level) → "FAIL" (for score), "PASS_WITH_WARNINGS" (summary) → extract per-rule status individually
   • checked_files ← [path to collaboration.md]
   • violations ← map each entry in violations array, preserving detail as message and location

4. Include mapped VR results in the rule_results list for scoring. SKIPPED rules (from delegation failure) are excluded from total_checks and passed_checks per the compliance score formula, and counted in summary.skipped_checks.

Step 3 — Apply Group B Rules (per folder/hierarchy)

Delegation Note: HR-1, HR-3, HR-4, and HR-5 check algorithms have been removed from this skill. Those structural/link-integrity checks are exclusively owned by hierarchy-validation (HX-1/HX-2, HX-3, HX-5, HN-1). The pre-condition gate guarantees those have already passed before this step executes.

HR-2 Check

• Read the parent collaboration.md and extract all control-type participants.
• Compare against sub-process folder names (strip ordinal prefix and Boundary suffix, compare case-insensitively with PascalCase normalization).
• FAIL if a sub-folder exists that cannot be matched to any control-type participant.

HR-6 Check

• Locate hierarchy-metadata.json.
• WARNING if absent.
• If present, compare last_updated against the modification time heuristic (use the latest <!-- Last Updated: --> comment found across all collaboration.md files within scope, or the most recent file mtime reported by file listing).

Step 4 — Apply Group C Rules (per level)

EP-1 Check

• Scan each collaboration.md for [R- citation patterns or a **Source Requirements**: line.
• FAIL if none found.

EP-2 Check

• For each child sub-folder within the target scope:
  1. Read the child's collaboration.md and collect its declared participant names.
  2. Identify the boundary entry-point participant (the boundary-type participant that serves as the interface to the parent). This participant is exempt — it may legitimately appear in the parent diagram as the decomposed control point.
  3. For all remaining internal participants (controls, entities, additional boundary types within the child scope), check whether any appear by name in the parent collaboration.md.
• FAIL if any internal child participant name is found in the parent diagram, indicating direct leakage of child-level detail into a higher abstraction level.
• Do NOT flag the decomposed control participant (whose name matches the child sub-folder after stripping ordinal prefix and Boundary suffix) — its presence in the parent is expected and valid.

EP-3 Check

• Scan each main.md for **Status**: and either **Last Updated**: or <!-- Last Updated:.
• WARNING if either is absent.

EP-4 Check

• For each decomposed participant in a collaboration.md, check that a %% decomposed: annotation exists on or near the participant declaration line.
• WARNING if absent.

Step 5 — Score and Aggregate

# SKIPPED rules are excluded from both total_checks and passed_checks.
# Record SKIPPED count separately in summary.skipped_checks.
compliance_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 results on ERROR-severity rules
  warnings = count of FAIL results on WARNING-severity rules

overall_status (evaluated top-to-bottom; first match wins):
  BLOCKED          → pre-condition-not-met (hierarchy-validation has not been run or did not achieve VALID/MOSTLY_VALID on the same target scope)
  COMPLIANT        → errors = 0 AND compliance_score ≥ 90
  MOSTLY_COMPLIANT → errors = 0 AND compliance_score ≥ 70
  NON_COMPLIANT    → errors > 3
  NEEDS_ATTENTION  → all other cases
                     (covers: errors > 0 AND errors ≤ 3;
                              errors = 0 AND compliance_score < 70)

Step 6 — Generate Reports

JSON Report (edps-compliance-report.json)

{
  "report_metadata": {
    "generated": "ISO8601 timestamp",
    "scope": "path to target folder or file",
    "mode": "strict | relaxed",
    "schema_version": "1.0"
  },
  "summary": {
    "overall_status": "COMPLIANT | MOSTLY_COMPLIANT | NEEDS_ATTENTION | NON_COMPLIANT | BLOCKED",
    "compliance_score": 0.0,
    "total_checks": 0,
    "passed": 0,
    "skipped_checks": 0,
    "failed_errors": 0,
    "failed_warnings": 0,
    "levels_scanned": 0,
    "diagrams_scanned": 0
  },
  "rule_results": [
    {
      "rule_id": "VR-1",
      "rule_name": "Single External Interface",
      "group": "A",
      "severity": "ERROR",
      "status": "PASS | FAIL | SKIPPED",
      "checked_files": ["path/to/collaboration.md"],
      "violations": [
        {
          "file": "path/to/collaboration.md",
          "location": "box OrderService boundary, line ~42",
          "detail": "Two external actors (UserPortal, AdminConsole) send directly to OrderService boundary without a shared gateway",
          "remediation": "Introduce a gateway control-type participant outside the box to route messages from both actors, then have only the gateway enter the boundary."
        }
      ]
    }
  ],
  "trend": {
    "previous_score": null,
    "delta": null,
    "note": "No previous report found for trend comparison."
  }
}

Markdown Report (edps-compliance-report.md)

# EDPS Compliance Report

**Generated**: [timestamp]  
**Scope**: [target path]  
**Mode**: [strict | relaxed]  
**Overall Status**: [status badge]

## Summary

| Metric | Value |
|--------|-------|
| Compliance Score | [score]% |
| Total Checks | [n] |
| Passed | [n] |
| Errors (blocking) | [n] |
| Warnings | [n] |
| Levels Scanned | [n] |
| Diagrams Scanned | [n] |

## Rule Results

### Group A — Boundary Diagram Rules

| Rule | Status | Violations |
|------|--------|------------|
| VR-1 Single External Interface | ✅ PASS / ❌ FAIL / ⚠️ WARN | [n] |
...

## Violations Detail

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

**File**: `path/to/collaboration.md`  
**Location**: [description of location in file]  
**Issue**: [specific description of the violation]  
**Remediation**: [concrete fix instruction]

---

## Remediation Priority

1. **Critical (Errors)**: Fix all ERROR violations before proceeding — these indicate structural violations of EDPS principles.
2. **Advisory (Warnings)**: Address WARNING violations to improve methodology alignment and documentation quality.

## Trend

[Score delta vs. previous report, or "No previous report found."]

---

Strict vs. Relaxed Mode

Behaviour	Strict	Relaxed (default)
WARNING violations block COMPLIANT status	Yes	No
EP-3 and EP-4 missing metadata treated as	ERROR	WARNING
VR-4 cohesion heuristic threshold	70 %	60 %
HR-6 missing metadata treated as	ERROR	WARNING
Report generated even when errors exist	No — exits with error summary first	Yes

---

Remediation Suggestions Reference

Rule	Common Fix
VR-1	Introduce a gateway control-type participant outside the box to funnel multiple actors into a single entry point
VR-2	Reorder the first message inside the box so an external actor's first target is always a boundary-type participant
VR-3	Remove the sub-folder for the non-control participant, or reclassify the participant type to control in the parent diagram
VR-4	Split participants with unrelated domains into separate box boundaries
HR-1, HR-3, HR-4, HR-5	These rules are now owned by hierarchy-validation — run hierarchy-validation --fix on the target scope to remediate structural link and naming issues
HR-2	Rename or remove the orphaned sub-folder, or add the missing control-type participant to the parent diagram
HR-6	Run any hierarchy-management decomposition or statistics command to regenerate hierarchy-metadata.json
EP-1	Add **Source Requirements**: [R-NNN] to the diagram header or inline [R-NNN] citations in the diagram description
EP-2	Remove child-level participant declarations from the parent diagram; reference the boundary as a single black-box participant
EP-3	Add **Status**: Active and <!-- Last Updated: YYYY-MM-DD --> to the main.md header
EP-4	Add %% decomposed: [ParticipantName] → [NN]-[ParticipantName]Boundary/collaboration.md after the participant declaration in the parent collaboration.md

---

Integration with Other Skills

• Run after hierarchy-management has generated or updated a hierarchy to validate its output.
• Run before integration-testing to ensure EDPS structure is sound before full test execution.
• Violations reported by edps-compliance inform change-management entries when structural changes are required to remediate.
• The compliance score trends feed into project-status-reporting health metrics.