Skip to main content

Release Governance

This document defines the durable release policy for the Maya workspace. Command details stay in .docs/verification.md, supply-chain assertions stay in .docs/security/supply-chain.md, ownership routing stays in .github/CODEOWNERS, and package consumption details stay in .docs/packages.

Release Readiness​

A release candidate is ready only when the change set has a clear owner, workspace-level impact is reflected in CHANGELOG.md, security-relevant changes are coordinated through SECURITY.md, and package-facing behavior links back to the canonical package guide instead of copying package documentation.

Before a release branch or tag is considered shippable, run the static documentation and supply-chain checks from the workspace root:

pnpm verify:docs-dx
pnpm security:supply-chain

pnpm verify:docs-dx covers the static documentation structure gate (node tools/verify-docs-structure.mjs), the WCP-014 surface migration map gate (pnpm verify:surface-migration-map), the package docs/API parity gate (node tools/verify-docs-api-parity.mjs), the agent capability map gate (node tools/verify-agent-capability-map.mjs), and the Docusaurus docs-site gate (pnpm verify:docs-site). pnpm security:supply-chain is the manual entry point for the static supply-chain gate.

pnpm release:gate remains the release gate for publishable artifacts. The exact command graph lives in .docs/verification.md and tools/gate-commands.mjs; this governance file should not restate the release-gate inventory. Evidence capture scripts are separate from the release gate and must not run in CI as a way to refresh committed evidence.

Release Checklist​

Before a v0 release candidate is handed off, verify these release inputs from the workspace root:

  • Docs index: .docs/README.md links the architecture overview, decision register, roadmap, backlog, package guides, verification guide, security policy, and release governance.
  • Package support: tools/workspace-package-registry.mjs still marks only @maya/assistant-composition, @maya/assistant-protocol, and @maya/assistant-ui as npmPublishable; @maya/claude-workspace and @maya/data-lab-module remain workspace-private validation packages, and @maya/docs remains an app-private docs site.
  • Package artifacts: pnpm pack:dry-run and pnpm smoke:consumer pass, including the WCP-023 guide consumer and WCP-025 product-kit consumer.
  • Docs and DX: pnpm verify:docs-dx and pnpm verify:verification-docs pass.
  • Supply chain: pnpm security:supply-chain passes and keeps npm publish restricted to pnpm-packed tarballs.
  • Final gate: pnpm release:gate passes for the exact commit being released.
  • Change history: CHANGELOG.md includes the release-impact summary under Unreleased or the target version heading.
  • Security coordination: SECURITY.md and .docs/security/supply-chain.md are updated when the change affects reporting, vulnerability handling, dependency policy, publish policy, or artifact contents.

Command details remain in .docs/verification.md and tools/gate-commands.mjs. This checklist names the release decision points; it must not duplicate the full release-gate command graph.

v0 Known Limitations​

v0 supports trusted build-time React modules imported explicitly by a developer-owned host. The following remain outside the v0 release:

  • end-user plugin marketplace, online install, remote ESM, iframe execution, module federation, micro-app runtime, and unknown third-party code execution
  • runtime sandboxing, plugin review/certification, or frontend grants as a security boundary
  • public built-in route replacement API, arbitrary page-internal patching, DOM selector hooks, and local built-in page slots
  • default user or assistant text message renderer replacement
  • automatic render pack discovery, import-time registration, and global render registries
  • ClaudeWorkspace and ClaudeWorkspaceRenderer React facades as publishable product-kit APIs
  • Claude built-in render pack exports and @maya/claude-workspace/styles.css
  • @maya/claude-workspace and @maya/data-lab-module npm publishability
  • SSR contract for ReactRenderRuntime

These limitations are governed by the decision register and detailed specs: .docs/architecture/workspace-composition-decisions.md, .docs/architecture/workspace-composition-v0-roadmap.md, and .docs/architecture/workspace-composition-linear-backlog.md.

Remaining Open Decisions​

The v0 release has closed the diagnostic registry, CompositionPolicy JSON shape, AssistantWorkspaceCompositionInput controller shape, package registry classification, and v0 grant semantics through their canonical specs and package guides. The remaining explicit post-v0 decisions are:

  • whether to publish a closed extension registry for future RenderHandle.kind values beyond the current contribution-to-handle mapping
  • the SSR contract for ReactRenderRuntime
  • the timing and context model for a public built-in route replacement API
  • the architecture for future untrusted external modules, including marketplace, sandbox, remote loading, and permission enforcement

Reopening or closing these decisions follows the decision-register reopen process and CODEOWNERS ownership.

Versioning And Tags​

Publishable package versions live in their package manifests. The publishable package set is declared in tools/workspace-package-registry.mjs: @maya/assistant-composition, @maya/assistant-protocol, and @maya/assistant-ui. When npm publish runs from a semver tag, the v* tag must match every publishable package version before publish can proceed. When npm publish runs from main, the workflow relies on package manifest versions and published-version preflight. Manual npm publish uses the protected npm-publish environment, npm provenance, pnpm-packed tarballs, and the release gate for the exact commit.

Classify public changes by the broadest affected contract:

  • patch: fixes, documentation clarifications, static policy updates, or visual value tuning that preserves public semantics.
  • minor: new public exports, documented states, public tokens, package subentries, or additive host integration behavior.
  • major: removed or repurposed public exports, documented states, CSS variables, data attributes, keyboard behavior, package contents, or release/security guarantees.

Package API classifiers use the highest reported level across public declarations, package subentries, CSS assets, token contracts, and documented states. A release can always choose a higher level than the classifier reports, but must not choose a lower level for a published package.

Changelog Policy​

CHANGELOG.md is the root change history for workspace-level release, security, governance, and user-facing behavior. Keep newest entries first, keep an Unreleased section for changes already merged but not tagged, and use durable categories such as Added, Changed, Fixed, Security, and Removed.

Package-root changelogs are intentionally not used. Package-specific entries in the root changelog should link to .docs/packages/assistant-ui.md, .docs/packages/assistant-protocol.md, .docs/packages/assistant-composition.md, .docs/packages/claude-workspace.md, or .docs/packages/data-lab-module.md when consumers or maintainers need installation, export, token, controller, composition-boundary, product-kit, or trusted sample module boundary details.

Security Coordination​

Security reports follow SECURITY.md. Security fixes should keep exploit detail out of public issues and commits until maintainers choose a disclosure path. When a security fix changes release behavior, package contents, evidence handling, dependency policy, or publish policy, update the root changelog and the relevant .docs/security policy in the same change set.

Artifact Boundaries​

Release artifacts must not carry duplicate documentation truth. Publishable packages keep tarballs focused on dist and LICENSE; package-root README.md, package-root changelogs, generated dist/docs/*, and copied docs/* package docs are disallowed. The package guides in .docs/packages remain canonical for consumers, while this file governs release process.

Ownership​

.github/CODEOWNERS routes review for publishable packages, workspace-private product/sample packages, release workflows, security policy, changelog policy, and package verification tooling. Code owner review is a repository policy signal; branch protection decides whether it is required before merge.