release: prepare v0.1.0-alpha.1

.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  github-release:
+    name: publish GitHub release
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify tag target and release notes
+        id: release
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          git fetch --force origin main:refs/remotes/origin/main --tags
+
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          NOTES="docs/releases/${VERSION}.md"
+          TAG_COMMIT="$(git rev-parse "${TAG}^{commit}")"
+
+          if ! git merge-base --is-ancestor "${TAG_COMMIT}" origin/main; then
+            echo "::error::Release tags must target commits reachable from origin/main."
+            echo "::error::Tag ${TAG} targets ${TAG_COMMIT}, which is not on origin/main."
+            exit 1
+          fi
+
+          if [[ ! -f "${NOTES}" ]]; then
+            echo "::error::Missing release notes file: ${NOTES}"
+            exit 1
+          fi
+
+          {
+            echo "tag=${TAG}"
+            echo "version=${VERSION}"
+            echo "notes=${NOTES}"
+            if [[ "${VERSION}" == *-* ]]; then
+              echo "prerelease=true"
+            else
+              echo "prerelease=false"
+            fi
+          } >>"${GITHUB_OUTPUT}"
+
+      - name: Publish GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          TAG="${{ steps.release.outputs.tag }}"
+          NOTES="${{ steps.release.outputs.notes }}"
+          PRERELEASE="${{ steps.release.outputs.prerelease }}"
+
+          if gh release view "${TAG}" >/dev/null 2>&1; then
+            echo "::notice::GitHub release ${TAG} already exists; leaving it unchanged."
+            exit 0
+          fi
+
+          args=(
+            release create "${TAG}"
+            --verify-tag
+            --title "${TAG}"
+            --notes-file "${NOTES}"
+          )
+
+          if [[ "${PRERELEASE}" == "true" ]]; then
+            args+=(--prerelease)
+          fi
+
+          gh "${args[@]}"

CHANGELOG.md

@@ -8,6 +8,10 @@ versions still track specification maturity rather than a released product.
 
 ## [Unreleased]
 
+No changes yet.
+
+## [v0.1.0-alpha.1] - 2026-06-24
+
 ### Added
 
 - **Release roadmap.** Added `ROADMAP.md` as the scheduled alpha-release plan,

ROADMAP.md

@@ -13,6 +13,8 @@ Every release cut must satisfy these gates on the release commit:
 
 - `cargo xtask verify` passes locally.
 - The available GitHub Actions checks for `main` are green.
+- Publication is triggered by pushing a `v*` tag whose target commit is reachable
+  from `origin/main`; release tags must not target unmerged branch commits.
 - `CHANGELOG.md` has a dated section for the release.
 - The GitHub milestone has no open issue that blocks the release scope.
 - Release notes state exactly what the release claims and what it does not

crates/edict-syntax/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "edict-syntax"
-version = "0.0.0"
+version = "0.1.0-alpha.1"
 description = "Edict language lexer, tokens, AST, and parser (Phase 1)"
 edition.workspace = true
 license.workspace = true

docs/README.md

@@ -9,6 +9,8 @@ The current specification set is:
   `rationale.md` files explain machinery and still-relevant tradeoffs.
 - [Release Roadmap](../ROADMAP.md): scheduled alpha milestones, release gates,
   and the GitHub issue/milestone map.
+- [Release Notes](./releases/v0.1.0-alpha.1.md): draft notes for the first
+  front-end alpha milestone.
 - [Syntax Topic](./topics/syntax/): current contract and verification matrix for
   the Phase 1 `edict-syntax` lexer/parser.
 - [SPEC - Edict Language v1](./SPEC_edict-language-v1.md): source syntax, type

docs/releases/v0.1.0-alpha.1.md

@@ -0,0 +1,65 @@
+# v0.1.0-alpha.1 Release Notes
+
+Target date: 2026-06-24
+
+Status: draft until the `v0.1.0-alpha.1` tag is created from `main`.
+
+## Release Type
+
+`v0.1.0-alpha.1` is the first Edict front-end milestone release. It tags the
+current parser, source-AST semantic validation, topic shelves, and local
+verification gate.
+
+This is not a complete compiler or admission-stack release.
+
+## Version Policy
+
+- `crates/edict-syntax` is versioned as `0.1.0-alpha.1`.
+- `xtask` remains an internal workspace helper at `0.0.0`.
+- `publish = false` remains in force for all workspace member packages.
+- Versions currently track repository/specification maturity, not crates.io API
+  stability.
+
+## Included
+
+- Phase 1 `edict-syntax` lexer/parser for the landed source-AST subset.
+- Phase 2 source-AST semantic validation through `SEMVAL-REQ-007`.
+- Syntax and semantic-validation topic shelves.
+- Library-hosted doctests for external topic Markdown examples.
+- `cargo xtask verify` as the local release gate.
+- Tag-triggered GitHub Release publication for tags that point at `main`.
+- Release roadmap and GitHub milestone schedule.
+
+## Explicit Non-Goals
+
+- No crates.io publish.
+- No canonical Core encoder.
+- No Core IR lowering from the source AST.
+- No canonical Core hash golden fixtures.
+- No compiler CLI.
+- No target profile conformance fixtures.
+- No target lowerers.
+- No admission tooling.
+- No target, Core, admission, or bundle-integrity claim.
+
+## Required Verification
+
+Before tagging:
+
+- `cargo xtask verify` must pass on the release commit.
+- GitHub Actions on `main` must pass for MSRV Rust 1.85.0 and stable Rust.
+- Issue #16 must have its release checklist completed or explicitly deferred.
+
+## Tagging Plan
+
+After the release-prep PR lands and the `main` release commit is verified:
+
+```text
+git tag -a v0.1.0-alpha.1 -m "v0.1.0-alpha.1"
+git push origin v0.1.0-alpha.1
+```
+
+Pushing that tag to GitHub triggers the release workflow. The workflow verifies
+that the tag target is reachable from `origin/main`, loads these release notes
+from `docs/releases/v0.1.0-alpha.1.md`, and publishes the GitHub Release as a
+prerelease. It does not publish crates.

xtask/src/main.rs

@@ -666,6 +666,28 @@ mod tests {
         assert_eq!(base, "origin/main");
     }
 
+    #[test]
+    fn release_workflow_publishes_only_main_reachable_tags() {
+        let root = repo_root().expect("repo root");
+        let workflow =
+            fs::read_to_string(root.join(".github/workflows/release.yml")).expect("workflow");
+        for needle in [
+            "tags:",
+            "\"v*\"",
+            "contents: write",
+            "git merge-base --is-ancestor",
+            "origin/main",
+            "docs/releases/${VERSION}.md",
+            "release create",
+            "--verify-tag",
+        ] {
+            assert!(
+                workflow.contains(needle),
+                "release workflow missing expected guard/action: {needle}"
+            );
+        }
+    }
+
     fn temp_root(name: &str) -> PathBuf {
         let mut dir = std::env::temp_dir();
         dir.push(format!("edict-xtask-{name}-{}", std::process::id()));