Gate package releases on mdcode documentation and example checks

[adrianbrowning]

Parent

#10

What to build

Add a release workflow that verifies the package, its tests, and its documentation examples before publishing. A release must not be published if mdcode detects documentation drift or example-validation failures.

Acceptance criteria

• The workflow runs the project test suite, build, documentation synchronization check, and runnable-example validation.
• It is triggered only by the documented release mechanism and publishes only after every required check passes.
• The publish step uses documented repository secrets or trusted publishing configuration.
• Failure output makes it clear which release gate failed.
• The release process is documented for maintainers.

Blocked by

• Define the canonical npm package identity and align metadata #3
• Provide a reusable CI script to check documentation synchronization #11
• Provide a CI example for validating runnable Markdown snippets #12

[adrianbrowning]

This was generated by AI during triage.

Agent Brief

Category: enhancement
Summary: Gate releases of @gcmdev/mdcode on tests, build, documentation freshness, and runnable-example validation.

Current behavior:
The repository has no GitHub Actions workflows or documented release mechanism. The package has a local prepublish build hook only; it does not run synchronization or runnable-example checks before publication.

Desired behavior:
A documented release workflow runs all required gates before publishing the canonical package. It exposes which gate failed and never reaches the publish step after test, build, drift-check, or runnable-example failure. The maintainer activates the final npm publishing trust/credentials.

Key interfaces:

• Release trigger — use one documented release mechanism and prevent publication from ordinary pull-request or branch workflows.
• Required gates — run the project tests, build, Provide a reusable CI script to check documentation synchronization #11 documentation-sync check, and Provide a CI example for validating runnable Markdown snippets #12 runnable-example validation before publishing.
• Failure reporting — preserve per-gate output so maintainers can identify the failed release gate.
• Publishing configuration — use the canonical @gcmdev/mdcode identity and document the required npm trusted-publishing configuration or repository secret.
• Maintainer release documentation — state the trigger, prerequisites, and recovery path.

Acceptance criteria:

• The release workflow runs tests, build, documentation freshness checks, and runnable-example validation before publication.
• A failed gate prevents publication and clearly identifies the failed stage.
• The workflow is triggered only through the documented release mechanism.
• Publication targets @gcmdev/mdcode and uses documented trusted publishing or repository-secret configuration.
• Maintainer documentation covers setup, triggering a release, and investigating failures.
• Workflow tests or dry-run checks verify gate ordering and no-publish-on-failure behavior where practical.

Out of scope:

• Implementing the drift-check recipe or runnable-example validation; those are Provide a reusable CI script to check documentation synchronization #11 and Provide a CI example for validating runnable Markdown snippets #12.
• Choosing the canonical npm package identity; that is Define the canonical npm package identity and align metadata #3.
• Automatically configuring npm organization permissions, trusted publishing, or repository secrets.

Why this needs a human:
The maintainer must configure and authorize the npm publishing identity and GitHub trust/secret settings, then approve the first real publication. An agent can prepare the workflow and documentation but cannot complete these account-level steps.

Verification status:
Confirmed: no current GitHub Actions workflow exists, and only a local prepublish build hook is present. This issue is blocked by #3, #11, and #12.