feat(installer): native-skills intermediary-state transition with deterministic validation

[dickymoore]

What

This PR implements the native-skills intermediary-state installer transition requested in the Road to V7 thread, while keeping existing command/help behavior stable for users.

Concretely, it adds deterministic canonical-id authority, compatibility projections, and replay-backed validation for the first converted capabilities (bmad-help, bmad-shard-doc, and bmad-index-docs) without requiring repo-wide conversion.

Why

Brian asked for a phased migration path so BMAD can safely move from current task/workflow command projection behavior to native skills, without attempting a one-shot conversion and without breaking existing tool surfaces.

The core risk addressed here is projection inconsistency and naming/authority drift across installers and tool adapters. This PR establishes explicit authority and deterministic validation evidence so transition quality is measurable and auditable.

No GitHub issue is linked yet; scope and acceptance criteria were defined in the Native Skills Transition forum thread and implemented on this branch.

Requested Direction (What Was Asked For)

This PR implements the requested direction:

• Support an intermediary state where legacy task-based artifacts and native-skill projections can coexist.
• Prove the path with a small core capability set before broader rollout.
• Preserve backward compatibility for user-facing help/command behavior.
• Avoid repeating per-tool naming/prefix logic by using canonical skill identity.
• Keep existing semantic source organization (tasks/workflows/phases) while making canonical naming and metadata authoritative in installer projections.

Before vs After

Before

• Installer generated _bmad/_config manifests/help catalog and tool projections with implicit identity derived from mixed sources (paths, frontmatter, module-help rows, adapter-specific logic).
• Compatibility contracts were not expressed as strongly as needed for transitional migration safety.
• Deterministic replay-backed causality evidence for “issuing component” claims was not fully enforced for transitioned capabilities.
• Post-IDE deterministic validation did not yet include index-docs.

After

• Canonical capability identity and authority are enforced through sidecar-driven contracts for transitioned capabilities.
• Installer projections remain backward-compatible while adding canonical and provenance columns/records for transition safety.
• Compatibility validators enforce additive schema expectations and loader-surface contracts.
• Post-IDE deterministic validation runs capability harnesses for:
  • help
  • shard-doc
  • index-docs
• Replay evidence contracts verify causality via isolated perturbation checks and deterministic negative-path diagnostics.

How

1) Added explicit authority + contract validators

• Added sidecar schema/contract validation and fail-fast behavior:
  • tools/cli/installers/lib/core/sidecar-contract-validator.js
• Added capability-specific authority validation:
  • tools/cli/installers/lib/core/help-authority-validator.js
  • tools/cli/installers/lib/core/shard-doc-authority-validator.js
  • tools/cli/installers/lib/core/index-docs-authority-validator.js
• Added sidecar metadata exemplars for transitioned capabilities:
  • src/core/tasks/help.artifact.yaml
  • src/core/tasks/shard-doc.artifact.yaml
  • src/core/tasks/index-docs.artifact.yaml

2) Added canonical alias/help projection safeguards

• Added alias normalization and canonical tuple handling:
  • tools/cli/installers/lib/core/help-alias-normalizer.js
• Added sidecar-aware help catalog generation and command-label reporting:
  • tools/cli/installers/lib/core/help-catalog-generator.js
• Added projection compatibility validators:
  • tools/cli/installers/lib/core/projection-compatibility-validator.js
• Extended manifest generation to preserve compatibility and add canonical/provenance projection fields:
  • tools/cli/installers/lib/core/manifest-generator.js

3) Wired deterministic capability validation into installer orchestration

• Updated installer orchestration and options plumbing:
  • tools/cli/installers/lib/core/installer.js
• Added deterministic validation harnesses:
  • tools/cli/installers/lib/core/help-validation-harness.js
  • tools/cli/installers/lib/core/shard-doc-validation-harness.js
  • tools/cli/installers/lib/core/index-docs-validation-harness.js

4) Updated tool adapters for transitional compatibility

• Codex projection path:
  • tools/cli/installers/lib/ide/codex.js
• GitHub Copilot loader compatibility:
  • tools/cli/installers/lib/ide/github-copilot.js
• Shared task/tool command projection parsing:
  • tools/cli/installers/lib/ide/shared/task-tool-command-generator.js

5) Added exhaustive regression coverage

• Extended installer component test suite:
  • test/test-installation-components.js
• Includes deterministic artifact generation + validation + negative-path coverage and now includes:
  • Test Suite 14 (help validation artifacts)
  • Test Suite 15 (shard-doc validation artifacts)
  • Test Suite 16 (index-docs validation artifacts)

Behavioral Guarantees Established in This PR

• Existing user-facing install and help discovery flows remain intact (npx bmad-method install, /bmad-help workflows).
• Canonical aliases (canonical, legacy, slash) resolve deterministically to one capability identity.
• Duplicate visible command surfaces for transitioned capabilities are rejected by validators/tests.
• Transitional projection contracts for help/task surfaces remain additive-compatible for existing consumers.
• Deterministic replay evidence exists for issuing-component claims and rejects self-attested/non-causal evidence patterns.

Scope and Non-Goals

In scope

• Intermediary-state transition mechanics for installer/projection/validation.
• Converted and validated exemplar capability set: help + shard-doc + index-docs.
• Deterministic validation and compatibility contracts required for safe rollout.

Out of scope

• Repo-wide conversion of all tasks/workflows to native skills.
• Final long-term metadata model for all future capabilities beyond the transitioned set.
• Non-installer product features unrelated to native-skills migration safety.

Testing

Executed on this branch:

• npm run test:install
  • Result: PASS (698 passed, 0 failed)
• npm test
  • Result: PASS (full chain: schema tests, refs tests, install tests, schema validation, lint, markdown lint, format check)

Additional verification artifacts maintained in wrapper planning docs:

• AC matrix: native-skills transition acceptance coverage and evidence
• deep-dive before/after explainer
• progress log with commit/test checkpoints

Risks and Mitigations

• Risk: contract complexity in installer core.
  • Mitigation: deterministic harnesses + explicit negative-path test matrix.
• Risk: compatibility regression in tool loaders.
  • Mitigation: compatibility validators and dedicated loader-facing tests.
• Risk: capability conversion drift in later waves.
  • Mitigation: published carry-forward conversion template and naming-hygiene checks.

Reviewer Guide

Suggested review order:

1. tools/cli/installers/lib/core/installer.js
2. tools/cli/installers/lib/core/manifest-generator.js
3. validators (sidecar + authority + projection-compatibility)
4. validation harnesses (help, shard-doc, index-docs)
5. test/test-installation-components.js (Suites 14-16 + compatibility suites)

Notes

This is intentionally opened as a draft PR to allow maintainers to review migration direction, naming/authority assumptions, and rollout strategy before merge decisions.

[dickymoore]

Closing this as superseded by the lean scoped replacement PR: #1844.\n\nReason: #1819 grew beyond the requested first-step PoC. #1844 keeps the scope to one duplicated shard-doc prototype skill path (), preserves legacy behavior, and limits installer/test changes for quick review.

[dickymoore]

Correction to previous note (escaped text): superseded PR is #1844.

Scope in #1844 is intentionally lean:

• one duplicated shard-doc prototype skill path: bmad-shard-doc-skill-prototype
• legacy shard-doc behavior retained
• minimal installer + test changes for fast review

[dickymoore]

Superseded by lean replacement PR #1844 (single shard-doc prototype path, minimal installer/test scope).