OKHP3 okhp3-process-validation-scoring
BP-SKILL: Business Process Agent Skill Suite · part of mermaid-diagram-bpmn · OverKill Hill P³
Purpose
Orchestrate the full validation suite across all BP-SKILL process artifacts and return a composite 0–100 quality score. The suite runs V1–V9 validation rules and returns a band classification with a binary publication gate verdict.
When to use this skill
- All process artifacts exist (pir.yaml + pns.yaml minimum) and user wants a publication readiness check
- You need a single quality score before passing artifacts to
okhp3-publication-handoff-packaging - User asks for a validation report or quality audit of a process documentation set
When NOT to use this skill
- PNS has not been authored: run
okhp3-process-narrative-authoringfirst - User only wants to validate a single artifact: use the artifact's own validate script directly
- Do not suppress V1–V3 errors: these are hard gates that must be resolved before publication
V1–V9 Validation Rules
| Rule | Severity | Artifact | Description |
|---|---|---|---|
| V1 | error | pns.yaml | Required top-level fields present; status valid; ≥4 babok_core_concepts; all 13 section keys present |
| V2 | error | pns.yaml | Every activity has non-empty description + actor_role_id; every business rule has non-empty source |
| V3 | error | pns.yaml | Every RACI entry has exactly one Accountable and ≥1 Responsible; every activity has a RACI entry |
| V4 | warning | pns.yaml | Activity descriptions containing semicolons, >200 chars, or starting with subordinate conjunctions |
| V5 | error | pns.yaml | Every KPI must have non-empty formula and data_source |
| V6 | error | pns.yaml | Every decision_point must have ≥2 outcomes; every exception_path must have non-empty handling |
| V7 | warning | pns.yaml | controls_and_compliance is empty; activities not covered by any control |
| V8 | error | pir.yaml | PIR completeness_score ≥ 70; ready_for_narrative = true |
| V9 | warning | bpmn-beta.mmd | bpmn-beta file present; validate-bpmn-beta passes; diagram has at least one lane |
Quality Score Bands
| Band | Score range | Meaning |
|---|---|---|
| A | 90–100 | Publication ready: all errors resolved, warnings minimal |
| B | 75–89 | Publication ready with minor warnings: may proceed |
| C | 50–74 | Below threshold: resolve errors before publication |
| D | 0–49 | Significant quality deficit: major rework required |
Publication gate: Band A or B (score ≥ 75) → ready_for_publication: true
Validation Report Schema
validation-report.yaml contains:
process_id: from PIRvalidation_date,validated_by_rolerules_run[]: each rule:rule_id,severity,status(pass|fail|warn),findings[]artifact_scores{}: per-artifact weighted scores:pir,pns,bpmncomposite_score: 0–100 weighted compositeband: A | B | C | Dready_for_publication: true | falseblocking_errors[]: rule IDs that must be resolved before publicationrecommendations[]: actionable items for each warning
Orchestration Workflow
scripts/run-validation-suite.mjs executes in order:
- Validate PIR: run
validate-pir.mjs; record V8 pass/fail - Validate PNS: run
validate-pns.mjs; record V1–V7 findings - Score PNS: run
score-pns-quality.mjs; record weighted score - Score PIR: run
score-intake-completeness.mjs; record completeness score - Validate BPMN (if present): run
validate-bpmn-beta.mjs; record V9 pass/fail - Compute composite score: weighted average across artifact scores
- Classify band: assign A/B/C/D based on composite score
- Set
ready_for_publication: true only if band A or B and no V1/V2/V3/V5/V6 errors
Handoff Instruction
When ready_for_publication: true, pass all artifacts to okhp3-publication-handoff-packaging.
When ready_for_publication: false, present blocking_errors[] to the user and return to the appropriate skill to resolve each error.
Execution contract
Apply this contract on every run so the artifact is trustworthy and reusable:
- State the input evidence, assumptions, and unresolved questions before drafting. Never invent missing process facts, owners, controls, dates, or approvals.
- Preserve stable identifiers and source traceability. When transforming an upstream artifact, retain its IDs and cite the source field or section for each derived decision.
- Produce the declared artifact exactly, including required fields and valid values. Keep unsupported, uncertain, or not-applicable items explicit instead of silently omitting them.
- Validate the result with the bundled script or fixture when available. Report validation status, warnings, and any manual review still required.
- Stop and request the missing input when a boundary, approval authority, or safety-critical rule cannot be inferred. A partial artifact with clearly marked open questions is safer than a confident fabrication.
If scripts/run-validation-suite.mjs cannot run, run each underlying artifact's own validate script individually and combine the results by hand using the weighting in references/validation-rules.md, and state in the output that the orchestrated run was not executed.
References
Load on demand:
references/validation-rules.md: V1–V9 severity descriptions, remediation guidance, and composite scoring weights
Scripts
scripts/run-validation-suite.mjs: orchestrates V1–V9 checks and returns composite score, band, and publication gate verdict
Assets
assets/fixtures/validation-report-example.yaml: canonical validation report for purchase-approval process set
Evaluation and release status
This skill orchestrates the underlying validate-pir.mjs and validate-pns.mjs validators. The former root-level evaluation notes referred to retired process-skill paths; the current canonical packages are okhp3-process-intake-and-scope and okhp3-process-narrative-authoring, and this repository does not claim those retired evaluations as live evidence. This skill's own orchestration logic (run-validation-suite.mjs) has no dedicated eval coverage beyond the maintainer-facing tests/validate-skill.test.mjs against assets/fixtures/validation-report-example.yaml — notably, nothing currently proves the composite scoring and band classification logic itself is correct, only that the fixture round-trips. Evidence status: not-run for task quality and skill uplift.
Version 0.2.0 (this pass) added the compatibility declaration, the orchestrator fallback instruction, and a sharper discovery-time boundary against single-artifact validation. Classified minor per the versioning table, not patch. No regression suite exists to run before this bump; that limitation is disclosed, not implied away.
About
Part of the BP-SKILL: Business Process Agent Skill Suite, published in overkillhill/mermaid-diagram-bpmn. MIT License.