Skip to content

Commit 332018a

Browse files
authored
chore(context7): drop the stale planning/ exclusion (#62)
* chore: migrate off the planning/ convention Replaces the two-axis planning/ + architecture/ convention with PR-body-as-spec, CONTEXT.md for vocabulary, and docs/adr/ for rejected alternatives, per modern-python/.github#67. - planning/ deleted in full, 53 files. changes/ held 25 design and change files that git history already carries. releases/ held 13 notes; 11 are byte-identical to the published GitHub Release bodies except for a "See also" footer pointing at planning/ paths that #51 retro-edited locally and never re-pushed, plus a local H1 on 0.3.1 — all of it dying with planning/. Two are not: the published bodies for 0.5.0 and 0.7.2 are shorter summaries than the local drafts. The Releases are still the record; the longer drafts stay in git history. deferred.md was empty. - The five decision records become docs/adr/0001..0005 in date order, frontmatter stripped, revisit triggers kept, cross-references renumbered. None carried supersedes/superseded_by, so nothing needed restating as prose. Two more rejected alternatives were rescued from prose that planning/ was about to take with it: 0006, the removed doctor preflight and the three arguments that retire it, from changes/2026-05-31.02; and 0007, why the composite action deliberately does not run actions/checkout, from a single decision-log line in changes/2026-06-08.03. - architecture/ carried a README and three capability pages, all prose about mechanism that semvertag/ states itself. One claim was enforceable and unenforced: a strategy sees one commit and nothing else. It is now the INVARIANT test tests/test_strategy_isolation.py, which walks the import closure of semvertag/strategies/. Verified against four cases: a strategy importing httpware fails it, a strategy importing semvertag.providers fails it, an httpx2 import added to semvertag/_commit_parse.py fails it through the closure rather than directly, and a strategy importing semvertag._errors — widening nothing — leaves it green. Sources restored byte-identically, suite green. - CONTEXT.md is authored from scratch; there was no architecture/glossary.md. Seven terms. The audit cut one the previous draft had listed: Bump, whose rejected synonyms ("bump level", "bump kind") appear nowhere outside AGENTS.md and architecture/, both rewritten or deleted here. It forced no source edits, but it did surface a docs defect too large to fix in this commit: four docs/ pages tell users the conventional-commits strategy scans every commit since the last tag, when the use-case fetches only the head commit of the default branch. Correcting the phrase alone would leave the false claim standing, so it is drafted as an issue instead of edited here. - AGENTS.md gains Workflow and Where-a-fact-goes and loses the planning lanes and the architecture/ promotion rule. The admission check applied to it also cut a "Reference directories (do not edit)" section naming _archive/bmad/ and _autosemver_reference/ — neither directory exists in the tree or in git history — and a commit-message section whose only live content restated conventional commits. docs/agents/domain.md is deliberately absent: origin/main has no docs/agents/ and AGENTS.md had no Agent skills section to link one from, so authoring domain.md alone would be a half-rollout of a separate convention. - justfile and lint-ci drop index/check-planning (this repo had no links.py); the offline lychee gate lands in _checks.yml as a links job (modern-python/.github#66), taking the tree from 3 errors to 0 over 46 unique links. mkdocs.yml excludes /adr/ from the published site, matching modern-di, so the decision records do not appear on semvertag.modern-python.org. Beyond the recipe, and the reason this is chore: and not docs: release.yml both hard-required planning/releases/<tag>.md for every stable tag and sourced the Release body from it, so deleting planning/ would have failed every future stable release. The gate is gone and the body is now GitHub's generated notes, matching modern-di's post-migration workflow, which dropped the same gate in 1ea74ee (modern-python/modern-di#449). This retires the mandatory-curated-notes policy; a release wanting prose is edited after the fact with gh release edit. modern-di's file was NOT copied verbatim: semvertag's release.yml also owns the Float major tag step that force-updates the v0 ref action consumers pin, which modern-di has no equivalent of. Copying verbatim would have deleted it and broken every uses: modern-python/semvertag@v0 on the next release, so only the notes handling was aligned. Verification: just lint-ci clean, just test 474 passed at 100% branch coverage, just docs-build strict green with no adr/ output, lychee --offline 0 errors, and no file outside .git references planning/, architecture/, check-planning, check-links or convention-version. * chore(context7): drop the stale planning/ exclusion The sibling commit on this branch deletes planning/, so the exclusion now names a directory that does not exist. Dropping the key rather than leaving an empty list: Context7's schema (https://context7.com/schema/context7.json) declares no required properties and gives excludeFolders a default of [], so an absent key and an empty list are equivalent. Absent matches the repos that never carried the line.
1 parent c56ed22 commit 332018a

72 files changed

Lines changed: 464 additions & 8132 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/_checks.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,3 +45,17 @@ jobs:
4545
- run: uv python pin ${{ matrix.python-version }}
4646
- run: just install
4747
- run: just test --cov-report xml
48+
49+
links:
50+
runs-on: ubuntu-latest
51+
steps:
52+
- uses: actions/checkout@v6
53+
# --offline blocks network requests and excludes every external URL, so this gate
54+
# is deterministic: it fails only on a relative link or file path a diff broke.
55+
- name: Check local links
56+
uses: lycheeverse/lychee-action@v2
57+
with:
58+
args: >-
59+
--offline
60+
--no-progress
61+
'**/*.md'

‎.github/workflows/release.yml‎

Lines changed: 7 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -30,47 +30,23 @@ jobs:
3030
- uses: extractions/setup-just@v4
3131
- uses: astral-sh/setup-uv@v7
3232

33-
# Curated release notes are MANDATORY for a stable tag. This runs BEFORE
34-
# `just publish` (which is irreversible) so a missing notes file aborts
35-
# the release before anything reaches PyPI — rather than silently shipping
36-
# with GitHub's auto-generated notes. Pre-release tags (a letter in the
37-
# name, e.g. 2.0.0rc1) are exempt and keep the auto-generated fallback.
38-
- name: Require curated release notes (stable tags)
39-
run: |
40-
set -euo pipefail
41-
if [[ "$GITHUB_REF_NAME" =~ [a-z] ]]; then
42-
echo "Pre-release ${GITHUB_REF_NAME}: curated notes not required."
43-
exit 0
44-
fi
45-
notes="planning/releases/${GITHUB_REF_NAME}.md"
46-
if [ ! -f "$notes" ]; then
47-
echo "::error::Stable tag ${GITHUB_REF_NAME} has no curated release notes at ${notes}. Write the notes, commit to main, and re-tag." >&2
48-
exit 1
49-
fi
50-
echo "Found curated release notes: ${notes}"
51-
5233
# PyPI is irreversible, so it runs FIRST: if it fails the job stops and no
5334
# GitHub Release or v0 move advertises a version that never reached PyPI.
5435
# `just publish` derives the version from $GITHUB_REF_NAME (the tag name).
5536
# Auth via PyPI Trusted Publishing (OIDC); no PYPI_TOKEN. Needs a Trusted
5637
# Publisher on the semvertag PyPI project (env: pypi, workflow: release.yml).
5738
- run: just publish
5839

59-
# Description source: planning/releases/<tag>.md if present (verbatim, no
60-
# auto-changelog appended); otherwise GitHub's generated notes. A tag with
61-
# a letter (0.9.0rc1) is a pre-release -> flagged so GitHub won't mark it
62-
# "Latest" and so the v0 float below is skipped.
40+
# The Release body is GitHub's generated notes, rendered from the squashed
41+
# PR titles since the previous tag — so a conventional-commit title is what
42+
# a reader gets. A release wanting prose is edited after the fact with
43+
# `gh release edit <tag> --notes-file`. A tag with a letter (0.9.0rc1) is a
44+
# pre-release -> flagged so GitHub won't mark it "Latest" and so the v0
45+
# float below is skipped.
6346
- name: Resolve release metadata
6447
id: meta
6548
run: |
6649
set -euo pipefail
67-
notes="planning/releases/${GITHUB_REF_NAME}.md"
68-
if [ -f "$notes" ]; then
69-
echo "body_path=$notes" >> "$GITHUB_OUTPUT"
70-
echo "generate_notes=false" >> "$GITHUB_OUTPUT"
71-
else
72-
echo "generate_notes=true" >> "$GITHUB_OUTPUT"
73-
fi
7450
if [[ "$GITHUB_REF_NAME" =~ [a-z] ]]; then
7551
echo "prerelease=true" >> "$GITHUB_OUTPUT"
7652
else
@@ -80,8 +56,7 @@ jobs:
8056
- name: Publish GitHub Release
8157
uses: softprops/action-gh-release@v3
8258
with:
83-
body_path: ${{ steps.meta.outputs.body_path }}
84-
generate_release_notes: ${{ steps.meta.outputs.generate_notes }}
59+
generate_release_notes: true
8560
prerelease: ${{ steps.meta.outputs.prerelease }}
8661
draft: false
8762

‎AGENTS.md‎

Lines changed: 66 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,79 @@
1-
# semvertag — Claude project guide
1+
# AGENTS.md
22

3-
## Architecture
4-
5-
> Quick orientation. The authoritative, code-current account of each capability
6-
> lives in [`architecture/`](architecture/). **When a change alters a
7-
> capability's behavior, update the matching `architecture/<capability>.md` in
8-
> the same PR** — that promotion is what keeps `architecture/` true.
9-
10-
`semvertag` funnels everything through one process: a human at a shell, the
11-
GitHub Action, and the GitLab CI component all invoke `semvertag tag`, which
12-
parses flags + environment into validated `Settings`, wires a **provider** and a
13-
**strategy** through a modern-di container, and runs the use-case. Invariants
14-
that must not break: the CLI is the single entry point all wrappers share;
15-
providers expose a forge-neutral contract (read commits/tags, create a tag)
16-
independent of GitLab-vs-GitHub REST differences; strategies answer only "given
17-
this repo signal, what bump level" with no network and no tag-history reads.
18-
19-
| Capability | File |
20-
|---|---|
21-
| CLI entry point, `Settings`, DI wiring, Action / CI wrappers | [`architecture/cli.md`](architecture/cli.md) |
22-
| Forge adapters (GitLab, GitHub) and their neutral contract | [`architecture/providers.md`](architecture/providers.md) |
23-
| Bump-level strategies (`branch-prefix`, `conventional-commits`) | [`architecture/strategies.md`](architecture/strategies.md) |
24-
25-
## Workflow
26-
27-
This project uses **Superpowers** (brainstorm → plan → TDD → review) with the
28-
portable two-axis planning convention. `architecture/` (repo root) is the living
29-
truth home; `planning/` records *how it got there*. **Start at the
30-
[Quick path](planning/README.md#quick-path-start-here)** in
31-
[`planning/README.md`](planning/README.md) to choose a lane (Full / Lightweight /
32-
Tiny), create a change file, and ship — that file is the authoritative spec. Run
33-
`just check-planning` to validate changes and `just index` to print the change
34-
listing.
35-
36-
Per feature: brainstorming → `design.md` → writing-plans → `plan.md` →
37-
executing-plans / subagent-driven-development → requesting-code-review →
38-
finishing-a-development-branch. Use TDD by default (red, green, refactor), git
39-
worktrees for isolation (`superpowers:using-git-worktrees`), the verification
40-
gate before claiming completion (`superpowers:verification-before-completion`),
41-
and a subagent code review before landing (`superpowers:requesting-code-review`).
42-
43-
Planning artifacts live under `planning/` (not `docs/`, so they're excluded from
44-
the mkdocs site automatically). When superpowers skills default to
45-
`docs/superpowers/specs/` or `docs/superpowers/plans/`, use the change file
46-
under `planning/changes/` here instead.
47-
48-
**Cutting a release (maintainers)** is tag-driven via
49-
[`.github/workflows/release.yml`](.github/workflows/release.yml): write the
50-
notes at `planning/releases/<version>.md` (used verbatim as the GitHub Release
51-
body), then push a bare semver tag off green `main` —
52-
`git tag 0.9.0 && git push origin 0.9.0`. The workflow runs `just publish` (the
53-
tag sets the version via `uv version $GITHUB_REF_NAME`; no `pyproject.toml`
54-
bump) to PyPI, then creates the GitHub Release, then floats the `v0` action tag
55-
— PyPI first, so a failed publish creates no Release. Pre-releases use the
56-
PEP 440 form (`0.9.0rc1`, not `0.9.0-rc1`). PyPI is irreversible; there is no
57-
CI gate (a tag is the commitment point). The dogfood (`semvertag.yml`) runs in
58-
dry-run and never auto-tags, so the tag you push is the only tag. If `just
59-
publish` succeeds but a later step fails (Release or `v0`), do **not** re-push
60-
the tag — PyPI rejects re-uploading an existing version. Create the GitHub
61-
Release and move `v0` by hand, or cut a new patch tag.
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
624

63-
## Commit messages
5+
## Project Overview
646

65-
Imperative present-tense, scoped where helpful:
7+
`semvertag` auto-tags a GitLab or GitHub repository with a semantic-version git tag from CI.
8+
[`CONTEXT.md`](CONTEXT.md) opens with what it does and owns the vocabulary — read it before naming a
9+
concept in code, a test name, or an issue title. It ships as a Python CLI plus two thin wrappers over
10+
it: a GitHub Actions composite (`action.yml`) and a GitLab CI Catalog component
11+
(`templates/semvertag.yml`).
6612

67-
- `providers: add HttpClient wrapper`
68-
- `docs: update README hero section`
69-
- `fix: handle empty default branch in GitLab provider`
13+
## Commands
7014

71-
No story-numbered prefixes (`land story X.Y`, `contextualise story X.Y`). Those
72-
belong to the retired BMad workflow.
15+
`just` (task runner) and `uv` (package manager). The [`justfile`](justfile) is the source of truth —
16+
`just --list`, or read it. The one thing it does not say: `just test` passes args through, so
17+
`just test tests/unit/test_branch_prefix_strategy.py -q` works.
7318

74-
## Reference directories (do not edit)
19+
## Architecture
7520

76-
- `_archive/bmad/` — retired BMad workspace. Historical specs, PRD,
77-
architecture, retrospectives, and 14 dense story files. Read for context;
78-
do not extend, do not delete.
79-
- `_autosemver_reference/` — the original Raiffeisen-internal `autosemver`
80-
package. Behavioral reference only — port logic and test shapes from it
81-
but never `git mv` files in or take it as a starter.
21+
A human at a shell, the GitHub Action, and the GitLab CI component all invoke the same
22+
`semvertag tag`, and `semvertag/` is short enough to read. What reading it will not tell you is why
23+
four of its shapes are load-bearing rather than incidental: the two forge adapters are independent
24+
copies sharing only the RFC 8288 pagination loop
25+
([ADR-0001](docs/adr/0001-forge-providers-not-unified.md)) and their status-to-error ladders stay
26+
duplicated for the same reason ([ADR-0003](docs/adr/0003-error-translators-not-tabled.md)); there is
27+
one verb and no `doctor` preflight ([ADR-0006](docs/adr/0006-no-doctor-preflight-command.md)); and
28+
the composite action deliberately does not check the repository out
29+
([ADR-0007](docs/adr/0007-composite-action-does-not-check-out.md)).
30+
31+
## Cutting a release (maintainers)
32+
33+
Push a bare semver tag off green `main` — `git tag 0.9.0 && git push origin 0.9.0`;
34+
[`release.yml`](.github/workflows/release.yml) does the rest and its comments say in what order and
35+
why. Two things that file cannot tell you: the tag is the commitment point, cut by convention only
36+
off a green `main` with no in-workflow CI gate; and if `just publish` succeeds but a later step
37+
fails, do **not** re-push the tag — PyPI rejects re-uploading an existing version, so create the
38+
Release and move `v0` by hand, or cut a new patch tag.
8239

83-
## Commands
40+
## Workflow
8441

85-
`just --list` is the source of truth. Non-obvious "which to use when":
42+
**The spec for a change is its PR body**, not a committed file: why, design, non-goals, verification,
43+
reviewed with the diff. There is no change file and no lane to choose. A trivial PR (typo, dep bump,
44+
formatter, CI tweak) ships a conventional-commit title with no body ceremony.
8645

87-
- `just lint` autofixes; `just lint-ci` is check-only and also runs the
88-
planning validator (`planning/index.py --check`, also `just check-planning`).
89-
- `just test` runs pytest with `--cov-branch` and a project-wide
90-
`fail_under = 100` gate (set in `pyproject.toml` addopts), so every branch
91-
must be covered. Pass args through:
92-
`just test tests/unit/test_branch_prefix_strategy.py -q`.
93-
- `just docs-build` — strict mkdocs build (`mkdocs build --strict`), the docs
94-
gate.
46+
Two things outlive the PR, and there are exactly two places to put them: an alternative **rejected**
47+
with reasoning becomes an ADR in [`docs/adr/`](docs/adr/) (`NNNN-slug.md`, sequential, with a revisit
48+
trigger), and real work **not scheduled** becomes a GitHub issue. There is no third state, and no
49+
separate truth-home directory — a behaviour change is reviewed with the diff, not promoted to a page.
9550

96-
## What the codebase ships
51+
### Where a fact goes
9752

98-
`semvertag` is a public-OSS auto-tagger for GitLab/GitHub/Bitbucket
99-
repositories. Two strategies (`branch-prefix`, `conventional-commits`), two
100-
providers implemented today (GitLab, GitHub), distributed as a Python CLI plus
101-
a GitHub Actions wrapper (`action.yml`) and a GitLab CI Catalog component
102-
(`templates/semvertag.yml`).
53+
Four homes, one owner each:
10354

104-
## Tag and release naming
105-
106-
Two distinct tag conventions coexist — confusing them is easy:
107-
108-
- **Release tags: bare semver, no `v` prefix** (`0.3.1`, `0.4.0`). `just publish`
109-
runs `uv version $GITHUB_REF_NAME` expecting bare semver; the branch-prefix
110-
strategy emits bare-semver tags by default; release URLs are
111-
`releases/tag/0.4.0`. When touching the CLI / `justfile` / publish flow, think
112-
bare semver — `$GITHUB_REF_NAME` is `0.4.0`, not `v0.4.0`.
113-
- **Action floating tag: `v`-prefixed** (`v0`). The `Float major tag` step in
114-
[`.github/workflows/release.yml`](.github/workflows/release.yml) prepends `v`
115-
to the release tag's major segment (`0.4.0` → `v0`) and force-updates the
116-
floating tag, so consumers can pin `uses: modern-python/semvertag@v0` per the
117-
GHA ecosystem convention. Skipped on pre-releases. When touching that step or
118-
action-consumer docs, think `v`-prefix.
55+
| Home | Holds |
56+
|---|---|
57+
| `semvertag/` | anything readable from the source — the default |
58+
| a named test | an **invariant**: must stay true, and a change could silently break it |
59+
| `docs/adr/` | a rejected alternative, with the reasoning that would otherwise be re-litigated |
60+
| `README.md` and `docs/` | anything a user needs |
61+
62+
Before writing a line anywhere:
63+
64+
> Can an agent get this by reading `semvertag/`? → **don't write it.**
65+
> Would a wrong change here fail a test? → it belongs **in the test**, not in prose.
66+
> Does a user need it? → **`README.md` / `docs/`**.
67+
> Otherwise it does not get written.
68+
69+
**Prose about mechanism has no home. There is no file to add a paragraph to.** This file included:
70+
it is always loaded, so a line that restates a docstring, a justfile comment, or `pyproject.toml`
71+
costs every turn and rots in two places at once. The workflow files here carry dense explanatory
72+
comments; re-telling them in this file is the failure mode to watch for.
73+
74+
An invariant is a test whose name is the claim, with a docstring opening `INVARIANT:` and a second
75+
paragraph naming **what breaks it** — design rationale, not a report of what this one test catches.
76+
Nothing enforces that docstring shape; it is read at review time. A relative link to an ADR *is*
77+
checked — CI runs lychee `--offline` over every `.md` — but a path named in a docstring or a comment
78+
is not. Both ADRs and `INVARIANT:` docstrings ratchet: nothing prunes a record once its call is
79+
settled. Keeping them lean is a standing habit.

‎CONTEXT.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# semvertag
2+
3+
Auto-tags a GitLab or GitHub repository with a semantic-version git tag from CI:
4+
it reads the head commit of the default branch and the tag history through the
5+
forge's REST API, asks a strategy how far the version should move, and creates
6+
the new tag. Shipped as a Python CLI plus two thin wrappers over it — a GitHub
7+
Actions composite (`action.yml`) and a GitLab CI Catalog component
8+
(`templates/semvertag.yml`).
9+
10+
## Language
11+
12+
A term is listed only when there is a synonym to reject, or a meaning subtle enough that code and
13+
docs must agree on it. General semver and CI vocabulary — tag, version, release, major/minor/patch —
14+
does not belong here, however heavily this project uses it.
15+
16+
**Forge**:
17+
A repository-hosting service semvertag talks to over REST — GitLab or GitHub today.
18+
_Avoid_: host. `host` is already spoken for by the same-origin pagination guard, whose two
19+
user-visible error strings say a `Link` header "points to a different host"; there it means scheme +
20+
netloc, not a forge.
21+
22+
**Provider**:
23+
The adapter for one forge — `GitHubProvider` / `GitLabProvider` under `semvertag/providers/`, matched
24+
structurally against the `Provider` protocol. Also the user-facing selector value
25+
(`SEMVERTAG_PROVIDER=github`). Note the collision: `semvertag/ioc.py` imports `modern_di.providers`
26+
in the same file, where a *provider* is a DI recipe. Say **provider** for the forge adapter and
27+
**modern-di provider** for the other.
28+
29+
**Strategy**:
30+
The rule that turns **one** commit into a `Bump`. It receives the head commit of the default branch
31+
and nothing else — no network, no tag history, no commit range. A strategy never picks a tag or a
32+
version; the use-case does that around it.
33+
34+
**Latest tag**:
35+
The bump baseline: the **highest by SemVer precedence** among the repo's SemVer-parseable tags — not
36+
the most recently created one, and not the tag reachable from HEAD. `_select_latest_semver_tag`
37+
sorts by `semver.Version` and takes the maximum.
38+
_Avoid_: last tag, most recent tag. Both read as "newest by date", which names a different tag the
39+
moment a patch on an older line is pushed after a newer minor.
40+
41+
**Outcome**:
42+
What a run did, as the closed sum `Created | DryRun | NoTags | AlreadyTagged | NoBump` in
43+
`semvertag/_outcome.py`. It is internal and free to grow — the renderers `match` it exhaustively, so
44+
a new variant is a type error until handled. Distinct from **`RunResult`**, the JSON wire DTO it
45+
projects onto, and from **status**, the one string field on that DTO. The wire status tokens are a
46+
frozen public contract (`schema_version` `"1.0"`, parsed by `jq` in `action.yml`); the `Outcome`
47+
variant names are not.
48+
49+
**Prerelease**:
50+
Two incompatible spellings live in this repo and only one is recognized as a bump baseline.
51+
**SemVer-form** (`1.0.0-rc.1`) parses, sorts by SemVer precedence, and finalizes on the next bump.
52+
**PEP 440** (`0.9.0rc1`) does not parse as SemVer and is skipped from selection entirely — yet that
53+
is the form semvertag publishes *itself* under, and what `release.yml` means by "pre-release". Say
54+
which form you mean.
55+
56+
**Release tag** / **floating major tag**:
57+
A release tag is **bare semver, no `v`** (`0.4.0`): what the tool emits, what `just publish` feeds to
58+
`uv version $GITHUB_REF_NAME`, and what `release.yml` triggers on. The floating major tag is
59+
**`v`-prefixed** (`v0`): a single moving ref `release.yml` force-updates so action consumers can pin
60+
`uses: modern-python/semvertag@v0`. Two conventions, one repo; a `v` on a release tag breaks
61+
`just publish`.

‎architecture/README.md‎

Lines changed: 0 additions & 25 deletions
This file was deleted.

0 commit comments

Comments
 (0)