| name | cpv-fix-validation |
| description | Maps CPV validation errors to mechanical per-error fix guides. Use when looking up remediation steps for CRITICAL/MAJOR/MINOR/NIT findings. Architectural migrations are handled by cpv-migrate-marketplace-architecture. Used dynamically via cpv-the-skills-menu (TRDD-478d9687).
|
| user-invocable | false |
Fix Validation — Error-to-Fix Index
Overview
Central error-to-fix lookup. Maps validation errors to fix guides in references/.
Formatter canon — lint only, NEVER format (user directive)
NEVER run a FORMATTER on any file: no ruff format, no prettier, no mdformat, no markdown formatter. Formatters reflow content and corrupt the structured Markdown that skills, agents, TRDDs, wikimem, obsidian notes, and YAML frontmatter depend on.
- Markdown / mdz / docs / TRDD / wikimem: lint-only. Run
markdownlint in REPORT mode, then fix each finding BY HAND with Edit. NEVER markdownlint --fix.
- Python / JS/TS: the LINTER's autofix is allowed —
ruff check --fix, eslint --fix. NEVER the FORMATTER (ruff format / prettier).
- JSON / YAML / config: lint/report only, fix by hand. No
prettier --write.
Why: a formatter (and markdown --fix) rewrites files opaquely and breaks the careful structure the author maintains. This is the same discipline as the fixer-agent scope guard ("never reformat a file you weren't sent to fix").
Prerequisites
- Report from
/cpv-validate-*
- Access to
references/
Instructions
The token-economical fix flow (validate → ledger → MECH → INTEL read-once → delta → terminate):
- Validate → compact ledger, not the full report.
remote_validation.py <mode> <root> --strict --json > <findings.json>, then cpv_fix_ledger.py build --json <findings.json> --text <ledger.txt>; read <ledger.txt> (by-file, MECH/INTEL split, BLOCKING pre-tagged) — never ingest the full .md report each iteration (cost ≈ turns × per-turn-context).
- MECH first (zero-LLM). Auto-apply the
mech bucket with cpv_codemod.py apply --json <findings.json> --apply before spending any model tokens.
- INTEL fix-as-you-go, read-once. Per
intel file: read ONLY the finding line ranges (tldr slice / Read offset+limit), apply ALL its fixes in the SAME turn, never re-read. The recipe is the ledger's inline suggestion; open plugin-error-index.md / marketplace-error-index.md ONCE per rule-TYPE (jump via TOC), not per finding. For category: architecture, use cpv-migrate-marketplace-architecture.
- Delta re-validate → terminate. Re-validate, rebuild the delta ledger, feed
cpv_fix_loop_state.py record (CONVERGED / CYCLE / STALLED). Full loop: iterative-fix-loop.
Checklist: validate→ledger → MECH-first → INTEL read-once → delta → terminate.
Output
Fix log → $MAIN_ROOT/reports/cpv-plugin-fixer-agent/<ts±tz>-<slug>.md.
Error Handling
No match → keyword search; flag missing references.
Examples
Input: [MAJOR] Missing plugin.json
Output: plugin-structure-fixes §1
Resources
- Plugin Error Index
validate_plugin.py · validate_skill.py · validate_skill_comprehensive.py · validate_hook.py · validate_agent.py · validate_command.py · validate_mcp.py · validate_lsp.py · validate_security.py · validate_rules.py · validate_xref.py · validate_settings_marketplace.py · validate_documentation.py · validate_encoding.py · validate_enterprise.py · validate_scoring.py · validate_cache.py · validate_telemetry.py — plugin-shipped env-var hazards · Semantic pillar — Channel MCP Server Source-Code Security · validate_marketplace cross-validation rules
- Marketplace Error Index
validate_marketplace.py · 1 RC-MKPL-* upstream cross-validation codes (v2.81.0+) · validate_marketplace_pipeline.py · Architecture / Layout Migration Warnings (7 signals)
- Schema-Parity Contract
What CPV does · The contract · What this contract does NOT say · What IS covered · Validator-gap protocol · Historical incidents · Related
- Iterative Fix Loop
Why a loop · Algorithm · Entry points — plugin path vs report path · Termination and safety · WARNING evaluation rules · Publish-blocking warning categories · Truly advisory warnings · Output contract
- Parallel scanning (v2.103.0+) —
validate → fix → re-validate loops were dominated by validator wall-time pre-rewrite (each pass ≈ 198 s on the CPV repo); v2.103.0+ rewrite makes each pass ≈ 17 s, so 10-iteration fix loops cost less than ONE pre-rewrite pass. No need to bundle/batch fixes for time reasons.
Table of contents · Performance summary · Environment knobs (disable selectively for debugging) · Scaffolded plugins (created via cpv-create-plugin / cpv-setup-plugin-repo) · Batch commands (cpv-batch-*) · Remote validation (cpv remote-mode + scaffolded publish.py) · When to disable parallelism · See also
- Empirical Loading Bugs
Path-form acceptance matrix · Override-vs-default semantics · Three silent footguns CC does NOT catch · CPV validators added 2026-04-18 · Anthropic docs corrections · Round 2 confirmations · Tests added · Untestable in headless mode · v2.23.2 false-positive sweep
- Cache-Audit Fixes
Overview · CA-01 — Static prefix violation in cached content · CA-02 — Hook writes to cached files (CLAUDE.md / settings.json) · CA-03 — Hook flips MCP server enabled/disabled or permission allow/deny · CA-04 — model: frontmatter forces an in-line model switch (any component) · CA-05 — Hook script runs unbounded output commands · CA-06 — Compaction/SubagentStart hook does not preserve cached prefix · CA-07 — context: fork/branch re-primes the cache from cold · (all seven are WARNING)
- Telemetry Hazard Fixes
Overview · CRITICAL: Plugin ships CLAUDE_CODE_PLUGIN_SEED_DIR · CRITICAL: Plugin ships CLAUDE_CODE_SHELL_PREFIX · CRITICAL: Plugin ships CLAUDE_CONFIG_DIR · CRITICAL: Plugin ships BETA_TRACING_ENDPOINT pointing at external host · CRITICAL: Plugin ships OTEL_LOG_RAW_API_BODIES set to a file URL · MAJOR: Plugin ships third-party-provider bypass env var · Reference: env vars plugins MUST NEVER ship
- Pipeline Migration
§0 — Detect canonical pipeline drift via RC-PIPELINE-DRIFT-001 · §0b — Remove legacy pipeline scripts via RC-LEGACY-PIPELINE-001 · §1 — Fix dangling script references · §2 — Migrate to whole-repo lint via cpv_lint_engine · §3 — Cross-platform Python — bash to Python, os.path to pathlib · §4 — Make publish.py idempotent — interrupted-publish recovery · §5 — Sanitize every script-input parameter against injection · §6 — #137-143 CI-parity defects
- Marketplace Upstream Drift
Name mismatch — RC-MKPL-NAME-MISMATCH · Version drift — RC-MKPL-VERSION-DRIFT · Unknown entry field — RC-MKPL-UNKNOWN-FIELD · Unknown source sub-field — RC-MKPL-UNKNOWN-SOURCE-FIELD · Source unreachable — RC-MKPL-UPSTREAM-UNREACHABLE · Description / author / keywords drift — RC-MKPL-METADATA-DRIFT · Per-batch bulk align — consolidated marketplace patch · Opt-out flags — when drift IS intentional
- Migration only: the repo-root
references/canonical-pipeline-migration-checklist.md (CPV ships it under references/, NOT inside this skill dir) — 87-check exit gate.
- MCP bundling: executables go in
servers/, referenced as ${CLAUDE_PLUGIN_ROOT}/servers/<name> (unique names).
