# Cyphal Parity Guard > Keep the Python Cyphal rewrite in wire-visible behavioral parity with the C reference at `reference/cy`. Use when auditing/reviewing parity drift, identifying wire/state-machine discrepancies, updating `src/pycyphal2/` to match reference behavior, replacing conflicting Python tests with C-parity expectations, and adding regression tests for every discovered divergence. API-level discrepancies are by design and are to be ignored; this skill focuses on wire-visible and state-machine behavior only. Use when this capability is needed. - Skill: `tomevault-io/cyphal-parity-guard` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/cyphal-parity-guard` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/cyphal-parity-guard/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/cyphal-parity-guard --- # Cyphal Parity Guard ## Overview Run a deterministic parity workflow for `pycyphal2` against `reference/cy` in two modes: - `sync` mode: identify divergences, patch Python implementation, and add/adjust regression tests. - `review` mode: report parity findings only, no edits. Apply the following defaults unless the user overrides them: - Target wire+state parity with `cy.c`. - Treat `cy.c` behavior as source of truth when Python tests conflict. - Add Python regression coverage for each confirmed divergence. - Ignore API-level discrepancies that do not affect wire/state behavior (e.g., differences in API design, error handling style, etc). ## Mode Selection Select mode from user intent: - Use `review` mode when asked to "review", "audit", or "find discrepancies". - Use `sync` mode when asked to "fix", "update", "bring in sync", or "correct divergences". - If intent is ambiguous, start in `review` mode and then switch to `sync` when requested. ## Source-of-Truth Order Use this precedence: 1. `reference/cy/cy/cy.h` for constants/API semantics. 2. `reference/cy/cy/cy.c` for wire-visible and state-machine behavior. 3. `reference/cy/model/` when C code intent is ambiguous. 4. `src/pycyphal2/` and existing tests as implementation artifacts, not normative authority. ## Workflow 1. Prepare context. - Confirm repository root. - Inspect touched files and current test baseline. - Load `references/parity-checklist.md` and use it as the audit checklist. 2. Build a discrepancy matrix. - Compare `reference/cy` behavior with `src/pycyphal2/_node.py`, `_wire.py`, and related modules. - Ignore differences that are not visible on the wire or in state machines (e.g., differences in API design, error handling style, etc). - Keep in mind that error handling differs significantly between C and Python; therefore, certain error-path-related discrepancies may be expected and should be noted as such in the matrix (e.g., where C would clamp invalid arguments, Python should raise ValueError, etc). Error handling must be Pythonic first of all. - For each discrepancy, record: - C anchor (`file:line` + behavior statement). - Python anchor (`file:line` + divergent behavior). - Impact and severity. - Needed test coverage. 3. Execute mode-specific actions. - In `review` mode: - Produce findings ordered by severity. - Include exact file/line anchors and missing regression tests. - Do not edit code. - In `sync` mode: - Implement fixes in `src/pycyphal2/`. - Update/remove conflicting test expectations when they contradict `cy.c`. - Add at least one regression test per divergence under `tests/`. 4. Validate. - Run targeted tests first for changed behavior. - Run full quality gates when feasible: - `nox -s test-3.12` - `nox -s mypy` - `nox -s format` - If full matrix is requested or practical, also run `test-3.11` and `test-3.13`. 5. Report. - Always return the discrepancy matrix (resolved or unresolved). - For `sync` mode, map every fixed divergence to specific tests. - Call out residual risks if any discrepancy remains untested. ## Repository Constraints Enforce project constraints while implementing parity fixes: - Preserve behavior across GNU/Linux, Windows, and macOS. - Keep support for all declared Python versions in `pyproject.toml` (currently `>=3.11`). - Keep async I/O in `async`/`await` style and maintain strict typing. - Keep formatting Black-compatible with line length 120. - Keep logging rich and appropriately leveled for unusual/error paths. ## Output Contract For parity reviews, return: - Findings first, ordered high to low severity. - File/line references for C and Python anchors. - Explicit statement when no discrepancies are found. - Testing gaps and confidence level. For parity sync work, return: - What changed in implementation. - What changed in tests and which divergences they cover. - Commands executed and notable pass/fail outcomes. ## Reference Map - `references/parity-checklist.md`: hotspot checklist, anchor patterns, and discrepancy matrix template. --- > Source: [OpenCyphal/pycyphal](https://github.com/OpenCyphal/pycyphal) — distributed by [TomeVault](https://tomevault.io).