Skip to content

ADR-0087 P3: MCP upgrade surface + RC rehearsal discipline #2648

Description

@os-zhuang

Part of #2643 (ADR-0087). The AI-native consumption channel for the D4 artifacts, plus the rehearsal topology (D6). Deferred behind P0–P2 and evidence-gated per the ADR (built when there are enough external consumers to justify the surface).

Depends on P2 (the MCP tools serve the change manifest + migration set).

Scope

D4 — MCP upgrade tools (@objectstack/mcp)

  • spec_changes(from, to) — any version pair, folded across majors from the composable per-major spec-changes.json.
  • spec_deprecations(stackPath) — which conversions my metadata currently triggers.
  • spec_migrate(dryRun) — preview / apply the chain.

A consumer-side agent asks "what breaks me between 10 and 14?" and gets data, not documentation.

D6 — RC rehearsal (topology inverts)

  • Every major is published to the next dist-tag at least one RC cycle before latest.
  • Document the consumer-pull model: a consumer-side agent subscribes to the RC, runs its own validate && typecheck && test (the P0 handshake → P1/P2 migrate → verify loop) in a branch, and opens its own migration PR. The framework only publishes the RC + D4 artifacts — it never executes other repos' CI.
  • The pre-publish hotcrm smoke stays (release-blocking, unchanged) as the framework-side floor. A framework-side "community smoke ring" is explicitly rejected (wrong direction — don't scale framework-side execution when consumers can execute themselves).

Acceptance criteria

  • The three MCP tools answer from spec-changes.json for an arbitrary from/to pair spanning multiple majors, with no separate documentation lookup.
  • A documented, reproducible RC-consumer loop exists (an agent can rehearse an upgrade against next before latest).
  • The Release workflow publishes next before latest for a major; hotcrm smoke remains the only release-blocking external gate.

Boundaries

  • The consumer-side autonomous-upgrade agent itself is out of scope (consumers / ADR-0033 toolchain own it); P3 makes it possible by exposing the surface.
  • Evidence gate: build the MCP tools + RC step when external-consumer demand justifies the operational surface (ADR-0087 §Boundaries, like ADR-0054 Phase 3).

Refs: #2643, ADR-0087 (D4 tools, D6), ADR-0025, ADR-0033.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    Fields

    No fields configured for Task.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions