plugin-validator: UX and coverage gaps

[Jamie-BitFlight]

Copied from Jamie-BitFlight/claude_skills#131

Story

As a developer using Claude Code skills, I want to plugin-validator: ux and coverage gaps so that the tooling becomes more capable and complete.

Description

4 sub-issues identified: (1) report counts validator results not files, (2) commands receive skill-specific SK005 warning, (3) hooks have zero validation, (4) missing hook validator.

Details

Source: Experimental validation of plugin_validator.py against all component types (2026-02-13)
Added: 2026-02-13
Last groomed: 2026-02-13
Plan: plan/tasks-2-validator-ux-coverage.md
File: ./plugins/plugin-creator/scripts/plugin_validator.py (2934+ lines)
Tests: ./plugins/plugin-creator/tests/ (12 test files, 93% pass rate per QA report)
QA report: ./plugins/plugin-creator/planning/plugin-validator-qa-report.md

Sub-issue 1: UX — report counts validator results, not files

Severity: UX bug
Lines: 2928-2931 (result collection loop), 2698-2702 (summary display)

Root cause: Lines 2928-2931 iterate over validators (not files), appending (path, result) for each validator. When 1 file has 4 validators (FrontmatterValidator, NameFormatValidator, DescriptionValidator, NamespaceReferenceValidator), the results list has 4 entries all pointing to the same path. The report loop at line 2630 then prints "PASSED" 4 times for 1 file, and the summary at line 2702 shows "Total files: 4".

Acceptance criteria:

• Running validator on 1 file shows "Total files: 1"
• Each validator result is labeled with the validator name (e.g., "FrontmatterValidator: PASSED")
• Summary counts unique files, not validator invocations

Sub-issue 2: Commands receive skill-specific SK005 warning

Severity: False positive
Lines: 1884-1900 (SK005 check in DescriptionValidator), 2896-2901 (validator selection)

Root cause: DescriptionValidator.validate() (line 1802) has no file-type awareness. It applies SK004 ("description too short") and SK005 ("missing trigger phrases") to all file types. The validator selection at line 2896 applies DescriptionValidator to SKILL, AGENT, and COMMAND equally. Commands have a different frontmatter schema — they use argument-hint, allowed-tools, agent fields and do not need trigger phrases in their description.

Acceptance criteria:

• SK005 only fires on SKILL files (not COMMAND or AGENT)
• SK004 fires on SKILL and AGENT files (both need meaningful descriptions) but not COMMAND
• New error code series CM001+ for command-specific checks (e.g., validate allowed-tools format, argument-hint presence)
• DescriptionValidator receives file type context (via constructor parameter or path inspection)

Sub-issue 3: Hooks have zero validation

Severity: Missing feature
Lines: 148-165 (detect_file_type returns UNKNOWN for .js hooks and hooks.json)

Root cause: FileType enum (line 141-145) has no HOOK variant. detect_file_type() only matches SKILL.md, plugin.json, agents/, commands/. Hook files (.js in hooks/ directories, hooks.json configs) fall through to UNKNOWN, which triggers the error at line 2920.

Acceptance criteria:

• FileType enum includes HOOK_SCRIPT and HOOK_CONFIG (or combined HOOK)
• detect_file_type() recognizes .js files in hooks/ directories
• detect_file_type() recognizes hooks.json files
• New error code series HK001+ for hook validation (e.g., valid JSON in hooks.json, valid event types, valid hook matcher patterns)
• New HookValidator class following existing Validator protocol
• Reference: /plugin-creator:claude-hooks-reference-2026 skill for hooks.json schema

Sub-issue 4: Dead code — nested skill resolution pattern

Severity: Code quality
Lines: 904-911 (in _resolve_skill_reference method of NamespaceReferenceValidator)

Root cause: Lines 904-911 search for plugins/{plugin}/skills/*/{name}/SKILL.md (nested category pattern). This pattern does not exist in the repository. Actual skill layout is plugins/{plugin}/skills/{name}/SKILL.md (flat). The direct check at lines 899-902 handles all real cases. The nested search at 904-911 is dead code. Additionally, lines 759-760 and 771-772 reference the nested pattern in error message strings.

Note: The original backlog item referenced lines 651-656 and 778-785 as dead code for _discover_skills and _discover_invocable_skills. Those methods do not exist in the current source. The actual dead code is in _resolve_skill_reference at lines 904-911.

Acceptance criteria:

• Remove lines 904-911 (nested skill resolution)
• Update error message strings at lines 759-760 and 771-772 to remove nested pattern references
• Verify no test depends on nested skill resolution (grep tests for skills/*/ double-nested patterns)

Dependencies

• Sub-issues 1-4 are independent and can be implemented in parallel
• Sub-issue 3 (hooks) is the largest — requires new FileType, new Validator class, new error codes
• Sub-issue 2 (command SK005) requires deciding on a command-specific error code series

Related prior work

• QA report documents 15 pre-existing test failures (93% pass rate) — check for conflicts before modifying validators
• /plugin-creator:claude-hooks-reference-2026 — hooks.json schema reference for sub-issue 3
• /plugin-creator:claude-skills-overview-2026 — skill vs command schema differences for sub-issue 2

Approach

Use /python3-development:add-new-feature to extend plugin_validator.py. Delegate implementation to @python-cli-architect. Each sub-issue is a separate task.

Acceptance Criteria

• Work matches description
• Plan or implementation complete

Context

• Source: Experimental validation of plugin_validator.py against all component types (2026-02-13)
• Priority: P1
• Added: 2026-02-13
• Research questions: None