ci: align release workflows with unified tag-push trigger (#35)

Both workflows now follow the same pattern:
- Trigger on tag push (fw-* or cli-*) + workflow_dispatch for re-runs
- Verify version in source (dist-manifest.yml / Cargo.toml) matches tag
- Create release automatically if it doesn't exist, or upload assets
  with --clobber if it does (fixes fw-4.0.0 duplicate release error)

Framework workflow gains: version verification, workflow_dispatch,
idempotent release creation.

CLI workflow changes: trigger moved from release:published to tag push,
removing the need to manually create releases before CI runs.

Updated CLAUDE.md release procedures to reflect the simplified flow.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: montfort

.github/workflows/release-cli.yml

@@ -1,14 +1,14 @@
 name: Release CLI
 
 on:
-  # Trigger when a release with cli-* tag is published via GitHub UI or API
-  release:
-    types: [published]
-  # Allow manual trigger (useful when release already exists without binaries)
+  push:
+    tags:
+      - 'cli-*'
+  # Allow manual trigger (useful for re-runs or when tag already exists)
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Release tag (e.g., cli-1.1.0)'
+        description: 'Release tag (e.g., cli-3.0.0)'
         required: true
 
 permissions:
@@ -25,36 +25,30 @@ jobs:
     outputs:
       tag: ${{ steps.resolve.outputs.tag }}
       version: ${{ steps.resolve.outputs.version }}
-      should_run: ${{ steps.resolve.outputs.should_run }}
     steps:
       - name: Resolve tag and version
         id: resolve
         shell: bash
         run: |
-          # Determine the tag from the trigger source
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             TAG="${{ github.event.inputs.tag }}"
           else
-            TAG="${{ github.event.release.tag_name }}"
+            TAG="${{ github.ref_name }}"
           fi
 
-          # Only process cli-* tags
           if [[ "$TAG" != cli-* ]]; then
-            echo "Skipping: tag '$TAG' is not a CLI release"
-            echo "should_run=false" >> "$GITHUB_OUTPUT"
-            exit 0
+            echo "ERROR: tag '$TAG' is not a CLI release (must start with cli-)"
+            exit 1
           fi
 
           VERSION="${TAG#cli-}"
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "should_run=true" >> "$GITHUB_OUTPUT"
           echo "Building CLI $VERSION from tag $TAG"
 
   build-cli:
     name: Build CLI (${{ matrix.target }})
     needs: [resolve-version]
-    if: needs.resolve-version.outputs.should_run == 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -142,15 +136,14 @@ jobs:
           find release-artifacts -type f \( -name "*.zip" -o -name "*.tar.gz" \) -exec cp {} release/ \;
           ls -la release/
 
-      - name: Upload to existing release or create new one
+      - name: Create or update GitHub Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         shell: bash
         run: |
           TAG="${{ needs.resolve-version.outputs.tag }}"
           VERSION="${{ needs.resolve-version.outputs.version }}"
 
-          # Check if release already exists
           if gh release view "$TAG" > /dev/null 2>&1; then
             echo "Release $TAG exists, uploading binaries..."
             gh release upload "$TAG" release/* --clobber
@@ -159,5 +152,6 @@ jobs:
             gh release create "$TAG" \
               --title "DevTrail CLI $VERSION" \
               --generate-notes \
+              --latest \
               release/*
           fi

.github/workflows/release-framework.yml

@@ -4,6 +4,11 @@ on:
   push:
     tags:
       - 'fw-*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Release tag (e.g., fw-4.1.0)'
+        required: true
 
 permissions:
   contents: write
@@ -14,12 +19,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref_name }}
 
-      - name: Extract version from tag
+      - name: Resolve tag and version
         id: version
         run: |
-          VERSION="${GITHUB_REF_NAME#fw-}"
+          TAG="${{ github.event.inputs.tag || github.ref_name }}"
+          VERSION="${TAG#fw-}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Packaging Framework $VERSION from tag $TAG"
+
+      - name: Verify dist-manifest.yml version matches tag
+        run: |
+          MANIFEST_VERSION=$(grep '^version:' dist/dist-manifest.yml | sed 's/version: *"\(.*\)"/\1/')
+          TAG_VERSION="${{ steps.version.outputs.version }}"
+          if [ "$MANIFEST_VERSION" != "$TAG_VERSION" ]; then
+            echo "ERROR: dist-manifest.yml version ($MANIFEST_VERSION) does not match tag version ($TAG_VERSION)"
+            exit 1
+          fi
 
       - name: Create distribution ZIP
         run: |
@@ -29,11 +48,21 @@ jobs:
           zip -r "../devtrail-fw-${{ steps.version.outputs.version }}.zip" .
           cd ..
 
-      - name: Create GitHub Release
+      - name: Create or update GitHub Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          gh release create "${{ github.ref_name }}" \
-            --title "DevTrail Framework ${{ steps.version.outputs.version }}" \
-            --generate-notes \
-            "devtrail-fw-${{ steps.version.outputs.version }}.zip"
+          TAG="${{ steps.version.outputs.tag }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          ASSET="devtrail-fw-${VERSION}.zip"
+
+          if gh release view "$TAG" > /dev/null 2>&1; then
+            echo "Release $TAG exists, uploading asset..."
+            gh release upload "$TAG" "$ASSET" --clobber
+          else
+            echo "Creating release $TAG..."
+            gh release create "$TAG" \
+              --title "DevTrail Framework $VERSION" \
+              --generate-notes \
+              "$ASSET"
+          fi

CLAUDE.md

@@ -76,40 +76,31 @@ git commit -m "chore: bump CLI version to X.Y.Z"
 # Push, create PR, merge to main
 ```
 
-### Step 3: Create GitHub release
+### Step 3: Create and push tag
 
 ```bash
-gh release create cli-X.Y.Z \
-  --title "DevTrail CLI X.Y.Z" \
-  --notes "Release notes here..." \
-  --latest
+git tag cli-X.Y.Z
+git push origin cli-X.Y.Z
 ```
 
-### Step 4: CI builds binaries automatically
-
-The `release-cli.yml` workflow triggers automatically when a release with a `cli-*` tag is published. It:
+The `release-cli.yml` workflow triggers automatically:
 
-1. Compiles for 4 platforms in parallel:
+1. Verifies `Cargo.toml` version matches the tag
+2. Compiles for 4 platforms in parallel:
    - `x86_64-unknown-linux-gnu` (Ubuntu)
    - `x86_64-apple-darwin` (macOS Intel)
    - `aarch64-apple-darwin` (macOS ARM)
    - `x86_64-pc-windows-msvc` (Windows)
-2. Packages each as `.tar.gz` (Unix) or `.zip` (Windows)
-3. Uploads all binaries to the existing release
+3. Packages each as `.tar.gz` (Unix) or `.zip` (Windows)
+4. Creates the GitHub release and uploads all binaries
 
-**If CI doesn't trigger** (e.g., release was created before workflow was merged), run manually:
+**If CI needs re-running**, trigger manually:
 
 ```bash
 gh workflow run release-cli.yml -f tag=cli-X.Y.Z
 ```
 
-### Step 5: Delete old release (optional)
-
-```bash
-gh release delete cli-OLD.VERSION --yes
-```
-
-### Step 6: Verify
+### Step 4: Verify
 
 ```bash
 gh release view cli-X.Y.Z --json assets --jq '.assets[].name'
@@ -135,6 +126,8 @@ Update version references in docs:
 - `README.md` and `docs/i18n/es/README.md` (versioning tables)
 - `dist/.devtrail/00-governance/QUICK-REFERENCE.md` (EN + ES footer)
 - `dist/.devtrail/00-governance/AGENT-RULES.md` (EN + ES footer)
+- `dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md` (EN + ES footer)
+- `dist/.devtrail/00-governance/C4-DIAGRAM-GUIDE.md` (EN + ES footer)
 
 ### Step 2: Commit and merge
 
@@ -153,8 +146,15 @@ git push origin fw-X.Y.Z
 ```
 
 The `release-framework.yml` workflow triggers automatically:
-1. Packages `dist/` contents into `devtrail-fw-X.Y.Z.zip`
-2. Creates the GitHub release with the ZIP as asset
+1. Verifies `dist-manifest.yml` version matches the tag
+2. Packages `dist/` contents into `devtrail-fw-X.Y.Z.zip`
+3. Creates the GitHub release with the ZIP as asset
+
+**If CI needs re-running**, trigger manually:
+
+```bash
+gh workflow run release-framework.yml -f tag=fw-X.Y.Z
+```
 
 ### Step 4: Verify