Skip to content

gustavo-meilus/superpipelines / .superpipelines/skills/superpipelines/parity-test-h/validator-protocol

validator-protocol

Unverified

Loaded by the run-parity-test-h entry skill to supply operating protocol and invariants for YAML config validation in the parity-test-h pipeline. Not user-invocable.

Validator — Operational Protocol

Protocol

1. DISCOVER

  1. Read inputs from the orchestrator execution context:
    • input_path: path to the input YAML config file to read.
    • findings_output_path: path where validator-findings.json must be written.
    • state_path: path to pipeline-state.json for status updates.
    • run_id: current run identifier.
    • root: resolved scope root.
  2. Verify input_path exists and is a readable file. If not: update pipeline-state.json phases[0].status = "blocked"; emit NEEDS_CONTEXT with message: "Input YAML config file not found at {input_path}. Provide a valid path and re-run."
  3. Read the file content and parse it as YAML. If the file is empty: write a zero-findings validator-findings.json and emit DONE_WITH_CONCERNS with message: "Input file at {input_path} is empty. Findings file written with zero entries."
  4. If the YAML is syntactically invalid (parse error): update pipeline-state.json phases[0].status = "blocked"; emit BLOCKED with message: "Input file at {input_path} is not valid YAML: {parse_error_detail}. Fix the syntax and re-run."

2. PROCESS

Step 2.1 — Check required fields:

Verify each of the following fields is present at the top level of the parsed YAML document:

name, version, environment, timeout, resources

For each missing field, create a finding:

{
  "id": "F-{NNN}",
  "category": "required_field",
  "key": "{field_name}",
  "message": "Required field '{field_name}' is missing.",
  "severity": "error"
}

Step 2.2 — Check type constraints:

For fields that are present, validate their types against the following rules:

FieldExpected typeNotes
namestringNon-empty
versionstringSemantic version pattern \d+\.\d+\.\d+ preferred but not enforced
timeoutintegerPositive integer (seconds); string values like "30s" are a type mismatch
environmentstringOne of: development, staging, production
resourcesmapping (object)Must be a YAML mapping, not a scalar or list
replicasintegerIf present, must be a positive integer
enabledbooleanIf present, must be a boolean (true/false); string "true" is a type mismatch
tagslistIf present, must be a YAML sequence

For each type mismatch, create a finding:

{
  "id": "F-{NNN}",
  "category": "type_mismatch",
  "key": "{field_name}",
  "expected_type": "{expected}",
  "actual_type": "{actual}",
  "actual_value": "{value_as_string_truncated_to_50_chars}",
  "message": "Field '{field_name}' expected {expected} but got {actual}.",
  "severity": "error"
}

Step 2.3 — Check deprecated keys:

Flag any of the following keys if present at any level in the YAML document:

legacy_mode, old_timeout, deprecated_env, use_legacy_auth, v1_compat

For each deprecated key found, create a finding:

{
  "id": "F-{NNN}",
  "category": "deprecated_key",
  "key": "{key_name}",
  "message": "Key '{key_name}' is deprecated. {replacement_hint}",
  "severity": "warning"
}

Replacement hints:

  • legacy_mode → "Use mode instead."
  • old_timeout → "Use timeout instead."
  • deprecated_env → "Use environment instead."
  • use_legacy_auth → "Use auth.method instead."
  • v1_compat → "Remove this key; v1 compatibility layer is no longer supported."

Step 2.4 — Assign sequential finding IDs:

Assign IDs in the order findings were discovered: F-001, F-002, F-003, … (zero-padded to 3 digits).

Step 2.5 — Sort findings:

Sort the findings list: errors first (sorted alphabetically by key), then warnings (sorted alphabetically by key).

Step 2.6 — Handle zero-finding case:

If no findings were produced (the YAML is fully valid), findings is an empty array and total_findings is 0. Emit DONE_WITH_CONCERNS with message: "No findings produced. The YAML config appears fully valid against the schema." — this is a concern because zero findings on a parity-test run may indicate the schema check did not execute as expected.

3. DELIVER

  1. Write validator-findings.json to findings_output_path using the Write tool. Structure:
{
  "source_path": "{input_path}",
  "total_findings": 0,
  "findings": []
}

Fields:

  • source_path: path of the input YAML file (verbatim from execution context).
  • total_findings: total count of all findings (errors + warnings).
  • findings: array of finding objects as defined in Steps 2.1–2.5.
  1. Update pipeline-state.json:

    • Set phases[0].status = "completed" (or "completed_with_concerns" if zero findings).
    • Set phases[0].outputs = [findings_output_path].
    • Set phases[0].outputs_summary = { "total_findings": N, "required_field_violations": N, "type_mismatches": N, "deprecated_keys": N }.
  2. Emit terminal status:

    • DONE — validator-findings.json written successfully with at least one finding.
    • DONE_WITH_CONCERNS — file written but zero findings (may indicate schema check did not run as expected), or input was empty.
    • NEEDS_CONTEXT — input file not found or not accessible.
    • BLOCKED — input YAML is syntactically invalid; or findings file could not be written.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall