feat(blueprint-plugin): guard ADR-number collisions in blueprint-adr-validate

[laurigates]

What

Adds a deterministic ADR-number collision guard to blueprint-adr-validate (the lightweight validation-only variant proposed in #1585).

blueprint-plugin/skills/blueprint-adr-validate/scripts/check-adr-numbers.sh reports three classes, emitting the STATUS=/ISSUE_COUNT= structured convention:

Type	Severity	Meaning
duplicate_adr_number	ERROR	Two working-tree files lead with the same NNNN-.
adr_number_collision	ERROR	A working-tree ADR's number is already held by a different filename on origin/main — the pre-merge parallel-PR case.
adr_missing_index_row	WARN	An ADR is not referenced from the ADR directory's README index.

It resolves docs/adrs/ (blueprint canonical) or docs/adr/, degrades to STATUS=OK when neither exists, and skips the base-ref comparison (still checking duplicates + index) when origin/main is unavailable — so it is parallel-safe (exit 0 on OK/WARN, 1 on ERROR).

Why

ADR numbers are chosen at branch time but only claimed at merge time, so two in-flight ADR PRs can pick the same number and both land. This is the FVH infrastructure #2015 collision: two ADRs both numbered 0038, a third assigned 0040 over the apparent gap, and the README index silently missed 0039/0040 for a week. blueprint-adr-validate validated ADR relationships but had no numbering guard, so the race was invisible until implementation time.

Per the issue, this is the lighter alternative (validation-only, no renaming automation). The full placeholder-number + merge-time-assignment automation remains open in #1585 if wanted later.

How

• New check-adr-numbers.sh + wiring into blueprint-adr-validate/SKILL.md (Step 2b + Agentic Optimizations) and REFERENCE.md.
• Regression test scripts/tests/test-check-adr-numbers.sh — git fixture, 8 assertions (clean→OK, base-ref collision→ERROR+exit1, within-tree dupe→ERROR, missing index→WARN, no ADR dir→OK, absent base ref→graceful degrade). Auto-discovered by run-skill-script-tests.sh.
• plugin-compliance-check.sh check_skill_body() guard asserting the SKILL.md retains the check-adr-numbers.sh invocation (per .claude/rules/regression-testing.md).

Verification

• shellcheck clean on both scripts; lint-shell-scripts.sh clean.
• Regression test: PASS=8 FAIL=0.
• Runs clean against this repo's own 19 ADRs (STATUS=OK).

Closes #1585

🤖 Generated with Claude Code

[github-actions]

Plugin Compliance Review

Plugin	plugin.json	Frontmatter	Body	Marketplace	Release Config	Bash Patterns	Descriptions	When-to-Use	Size	Overall
blueprint-plugin	✅	✅	✅	✅	✅	✅	✅	✅	⚠️	⚠️

Recommendations

• ⚠️ blueprint-plugin/blueprint-feature-tracker-sync: SKILL.md is 17309 chars (~4327 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-work-order: SKILL.md is 11513 chars (~2878 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-claude-md: SKILL.md is 11076 chars (~2769 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/document-detection: SKILL.md is 12442 chars (~3110 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-status: SKILL.md is 14947 chars (~3736 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-story-audit: SKILL.md is 11235 chars (~2808 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/document-linking: SKILL.md is 11208 chars (~2802 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-derive-plans: SKILL.md is 10183 chars (~2545 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-upgrade: SKILL.md is 19649 chars (~4912 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)
• ⚠️ blueprint-plugin/blueprint-init: SKILL.md is 21578 chars (~5394 tokens, >10000) — consider extracting to REFERENCE.md or scripts/ (ceiling: 26000 chars / ~6500 tokens)