feat(installer): native-skills intermediary-state transition (help/shard-doc/index-docs)

[dickymoore]

Summary

This PR delivers the native-skills intermediary-state transition for BMAD core installer behavior, with a narrow but end-to-end implementation across the first converted capabilities (help, shard-doc, index-docs).

Goal achieved: support native-skill authority while preserving current user-facing compatibility surfaces and avoiding a disruptive one-shot migration.

Why This Change Was Needed

Before this work, installer behavior depended on a growing mix of task/workflow surfaces and tool-specific naming/projection logic. That made rollout risky for full-skill migration because:

• canonical identity for a capability was not consistently authoritative across source, projection, and install outputs
• compatibility rules were implicit and scattered
• validation evidence was insufficiently deterministic for release confidence

This PR introduces a clearer model:

• source-of-truth metadata lives in per-capability sidecar manifest (reference/manifest.yaml)
• legacy/task surfaces are projected additively for compatibility
• installer validation harnesses enforce canonical/compatibility contracts deterministically

Scope

Implemented capabilities in this transition slice

• bmad-help (first conversion path + compatibility projection)
• bmad-shard-doc (extended conversion path)
• bmad-index-docs (extended conversion path)

Core implementation themes

• Sidecar authority split and precedence rules
• Canonical skill-name / alias normalization
• Additive projection generation for legacy consumer surfaces
• Deterministic validation artifact suite + replayable evidence
• Multi-surface installer compatibility gate behavior

Behavioral Guarantees / AC Coverage

• Native-skill authority can coexist with legacy task-based artifacts
• Installer discovers/validates/projects converted capabilities end-to-end
• Existing user-facing command/help compatibility remains stable through transition
• Duplicate visible surfaces for the same capability are rejected/guarded
• Delivery remains narrow/releasable (not a repo-wide conversion)

Files and Areas Touched (high level)

• tools/cli/installers/lib/core/*
  • authority validators
  • alias normalization
  • catalog/projection generators
  • deterministic validation harnesses (help, shard-doc, index-docs)
• tools/cli/installers/lib/ide/*
  • installer-side projection/registration paths for supported IDE/tool outputs
• src/core/tasks/*
  • task artifacts + authority metadata inputs for converted capabilities
• test/test-installation-components.js
  • expanded coverage for installer component contract behavior

Validation

Executed repeatedly during implementation and review:

• npm run test:install
• npm test

plus targeted deterministic harness/replay evidence checks for:

• help conversion/projection authority
• shard-doc conversion/projection authority
• index-docs conversion/projection authority

Review Process

• Work was driven using BMAD workflows (planning -> implementation -> adversarial review).
• High/medium review findings were remediated before finalizing.
• Remaining follow-ups are documented as explicit backlog/next-step candidates.

Additional Note: Test Suite Refactor PR

A follow-on maintenance PR has been opened to address test maintainability by splitting the monolithic installation component test file into ordered modular suites (no behavior change):

• refactor(test): split installation component suites into modular files #2

That PR targets this branch and is intentionally separated to keep migration logic review distinct from test-structure refactor review.

Risks / Follow-ups

• Continue capability-by-capability migration using the same authority/projection/validation contract.
• Keep naming canonicalization strict to avoid reintroducing per-tool prefix drift.
• Expand deterministic compatibility-gate coverage as additional capabilities migrate.

[dickymoore]

Superseded by feature/native-skills-lean-shard-doc-prototype and upstream PR bmad-code-org#1844.