# Evolution: tag-auto-discovery -- Automated Semantic Version Tag Resolution

**Project**: nWave Release Train
**Feature**: tag-auto-discovery -- CLI script for automated tag lookup in release workflows
**Date**: 2026-02-23
**Duration**: ~18 minutes (17:20 - 17:38 UTC)
**Status**: Complete -- all TDD steps reached COMMIT phase

---

## What Was Built

A standalone Python CLI script (`scripts/release/discover_tag.py`) that auto-discovers the highest semantic version tag for the nWave release train. Eliminates manual tag lookup when triggering RC and Stable releases via GitHub Actions UI.

Accepts `--pattern dev` or `--pattern rc`, sorts tags using `packaging.Version` (correct integer ordering: dev11 > dev9), outputs structured JSON with resolved tag, version, and staleness information.

### Phase 1 -- Tag Discovery Script (Step 01-01)

Core discovery logic: CLI with `--pattern`, `--validate`, `--tag-list` arguments. JSON output with `tag`, `version`, `found`, `commits_behind`. Exit codes: 0 (found), 1 (not found), 2 (invalid input). Pure functional style. 12 unit tests.

### Phase 2 -- Staleness Detection (Step 02-01)

Added `commits_behind` via `git rev-list --count TAG..HEAD`. 3 integration tests using `tmp_path` git repositories.

---

## Key Decisions

1. **Standalone script over extending existing scripts** -- Different responsibility from `next_version.py`. Clean separation of concerns.
2. **`--tag-list` parameter for testability** -- Enables pure unit testing without git. Workflow passes live tags; tests pass synthetic lists.
3. **Commit-distance staleness over calendar days** -- Measures unreleased commits after tag, not time since creation. A recent tag with 0 new commits is not stale; an old tag with 12 new commits is.

---

## Files

| File | Action |
|------|--------|
| `scripts/release/discover_tag.py` | Created -- CLI script (~5.5 KB) |
| `tests/release/test_discover_tag.py` | Created -- 15 test scenarios (~16.6 KB) |
| `tests/release/conftest.py` | Modified -- 4 tag-list fixtures |

---

## Pending Work

Workflow integration -- wiring `discover_tag.py` into `release-rc.yml` and `release-prod.yml` with `resolved_tag` propagation. Architecture document contains complete wiring specification.
