beacon-framework 0.2.0__tar.gz → 0.3.0__tar.gz

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beacon-framework
-Version: 0.2.0
+Version: 0.3.0
 Summary: Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery
 Project-URL: Repository, https://github.com/darth-veitcher/beacon
 Author: darth-veitcher
@@ -37,15 +37,21 @@ That writes the BEACON skeleton into the current directory and wires up Claude C
 ## Commands
 
 ```bash
-beacon init [--here] [--ai claude]      # install into a project (idempotent)
-beacon upgrade [--here]                 # refresh framework files only
-beacon check [--here]                   # validate the install
-beacon integration list                 # list AI integrations
-beacon integration add <name>           # wire up an AI tool
-beacon integration remove <name>        # remove an AI tool
-beacon version
+beacon init [--here] [--ai claude]        # install into a project (idempotent)
+beacon upgrade [--here]                   # refresh framework files only
+beacon check [--here]                     # validate the install (files-present)
+beacon doctor [--here] [--strict]         # semantic health check (placeholders, stale notes, ADR gaps, drift)
+beacon integration list                   # list available integrations
+beacon integration add <name> [--here]    # add an integration (e.g. `claude`, `release`)
+beacon integration remove <name> [--here] # remove an integration
+beacon --version  /  beacon -V            # show installed version
 ```
 
+### Integrations
+
+- **`claude`** — Claude Code slash commands and the `<!-- BEACON -->` block in `.claude/CLAUDE.md`. Installed by default.
+- **`release`** — Production-ready release pipeline: a GitHub Actions workflow that uses `python-semantic-release` + PyPI Trusted Publishing to ship `main` pushes to PyPI and `develop` pushes to TestPyPI. Drops `PUBLISHING.md` with the one-time setup instructions and injects a fenced `[tool.semantic_release]` block into your `pyproject.toml`.
+
 ## What gets installed
 
 ```

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/README.md

@@ -17,15 +17,21 @@ That writes the BEACON skeleton into the current directory and wires up Claude C
 ## Commands
 
 ```bash
-beacon init [--here] [--ai claude]      # install into a project (idempotent)
-beacon upgrade [--here]                 # refresh framework files only
-beacon check [--here]                   # validate the install
-beacon integration list                 # list AI integrations
-beacon integration add <name>           # wire up an AI tool
-beacon integration remove <name>        # remove an AI tool
-beacon version
+beacon init [--here] [--ai claude]        # install into a project (idempotent)
+beacon upgrade [--here]                   # refresh framework files only
+beacon check [--here]                     # validate the install (files-present)
+beacon doctor [--here] [--strict]         # semantic health check (placeholders, stale notes, ADR gaps, drift)
+beacon integration list                   # list available integrations
+beacon integration add <name> [--here]    # add an integration (e.g. `claude`, `release`)
+beacon integration remove <name> [--here] # remove an integration
+beacon --version  /  beacon -V            # show installed version
 ```
 
+### Integrations
+
+- **`claude`** — Claude Code slash commands and the `<!-- BEACON -->` block in `.claude/CLAUDE.md`. Installed by default.
+- **`release`** — Production-ready release pipeline: a GitHub Actions workflow that uses `python-semantic-release` + PyPI Trusted Publishing to ship `main` pushes to PyPI and `develop` pushes to TestPyPI. Drops `PUBLISHING.md` with the one-time setup instructions and injects a fenced `[tool.semantic_release]` block into your `pyproject.toml`.
+
 ## What gets installed
 
 ```

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "beacon-framework"
-version = "0.2.0"
+version = "0.3.0"
 description = "Light-touch, pragmatic, artifact-driven framework for AI-assisted software delivery"
 readme = "README.md"
 license = "MIT"
@@ -33,6 +33,7 @@ Repository = "https://github.com/darth-veitcher/beacon"
 
 
 
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/beacon"]
 # Include the bundled resources tree (markdown templates, prompts, .gitkeep
@@ -101,6 +102,7 @@ exclude_commit_patterns = ["^chore\\(release\\):"]
 
 
 
+
 [dependency-groups]
 dev = [
     "pytest>=8.0",

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/src/beacon/__init__.py

@@ -1,3 +1,3 @@
 """BEACON Framework: lifecycle and discipline for artifact-driven AI-assisted delivery."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/src/beacon/cli.py

@@ -8,6 +8,7 @@ import typer
 from rich.console import Console
 
 from beacon import __version__, installer, integrations
+from beacon.doctor import Status, run_all, summarise
 from beacon.manifest import MANIFEST_RELPATH, Manifest
 from beacon.upgrader import upgrade as upgrade_project
 
@@ -150,6 +151,40 @@ def check(
     )
 
 
+@app.command()
+def doctor(
+    path: Path | None = typer.Argument(None, help="Project directory (default: cwd)."),
+    here: bool = typer.Option(False, "--here", help="Doctor the current directory."),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Promote warnings to failures (CI mode).",
+    ),
+) -> None:
+    """Run semantic health checks against an installed BEACON project.
+
+    Where ``beacon check`` verifies that framework files *exist*, ``beacon
+    doctor`` examines their *content* — flags placeholder text, stale work
+    notes, ADR gaps, and drifted framework files. Use ``--strict`` in CI.
+    """
+    root = _resolve_root(here, path)
+    checks = run_all(root)
+    colour = {
+        Status.OK: "green",
+        Status.WARN: "yellow",
+        Status.FAIL: "red",
+    }
+    for c in checks:
+        console.print(f"[{colour[c.status]}]{c.icon}[/{colour[c.status]}] {c.name}: {c.message}")
+    ok, warn, fail, exit_code = summarise(checks, strict=strict)
+    console.print(
+        f"\n[dim]ok={ok}  warn={warn}  fail={fail}"
+        f"{'  (strict: warn→fail)' if strict and warn else ''}[/dim]"
+    )
+    if exit_code:
+        raise typer.Exit(code=exit_code)
+
+
 @integration_app.command("list")
 def integration_list() -> None:
     """List available AI integrations."""

beacon_framework-0.3.0/src/beacon/doctor.py

@@ -0,0 +1,265 @@
+"""Semantic health checks for an installed BEACON project.
+
+Where ``beacon check`` only verifies that the framework files exist, ``beacon
+doctor`` looks at their *content* — catches placeholder text, stale work
+notes, ADR gaps, and drifted framework files. Each check returns a tri-state
+result so the agent (or a human) sees which areas of the project have rotted.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from importlib import resources
+from pathlib import Path
+
+from beacon.manifest import Manifest
+
+STALE_SESSION_AGE = timedelta(days=30)
+"""Sessions older than this trigger a promote-or-delete warning."""
+
+ADR_HEURISTIC_COMMITS = 20
+"""Below this commit count the ADR-coverage check stays quiet."""
+
+PLACEHOLDER_TOKENS = (
+    # Markers from the shipped problem-statement template (Background/00-…)
+    "[Replace with your problem statement]",
+    "[Specific person, role, or team",
+    "[When and where they encounter this problem]",
+    "[What they do today and why it falls short]",
+    "[Outcome 1",
+    "[One paragraph on the business or human impact",
+    "[Technical, organisational, or timeline constraints",
+    # Markers from the architecture template (Background/01-…)
+    "[Project Name]",
+    "[one-line project description]",
+    # Markers from the roadmap template
+    "[bullet title]",
+    "[Hardcoded end-to-end]",
+)
+
+
+class Status(str, Enum):
+    OK = "ok"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass
+class Check:
+    name: str
+    status: Status
+    message: str
+
+    @property
+    def icon(self) -> str:
+        return {Status.OK: "✓", Status.WARN: "!", Status.FAIL: "✗"}[self.status]
+
+
+def _resource_root() -> Path:
+    return Path(str(resources.files("beacon").joinpath("resources")))
+
+
+def _check_manifest(root: Path) -> Check:
+    manifest = Manifest.load(root)
+    if manifest is None:
+        return Check(
+            "manifest",
+            Status.FAIL,
+            f"No BEACON manifest at {root}/project-management/.beacon/init-options.json. "
+            "Run `beacon init` first.",
+        )
+    return Check("manifest", Status.OK, f"BEACON {manifest.beacon_version} installed.")
+
+
+def _check_problem_statement(root: Path) -> Check:
+    path = root / "project-management/Background/00-problem-statement.md"
+    if not path.exists():
+        return Check(
+            "problem-statement",
+            Status.FAIL,
+            f"Missing {path.relative_to(root)}. Run `beacon init` or `beacon upgrade`.",
+        )
+    content = path.read_text()
+    hits = [tok for tok in PLACEHOLDER_TOKENS if tok in content]
+    if hits:
+        return Check(
+            "problem-statement",
+            Status.FAIL,
+            f"Placeholder text still in problem statement: {', '.join(hits)}. "
+            "Fill in 00-problem-statement.md before opening a feature branch.",
+        )
+    return Check(
+        "problem-statement",
+        Status.OK,
+        "Problem statement contains no template placeholders.",
+    )
+
+
+_ACTIVE_BULLET_PATTERN = re.compile(r"^\*\*#\d+\s*—.+\*\*", re.MULTILINE)
+_TEMPLATE_BULLET_PATTERN = re.compile(r"^\*\*#N\s*—\s*\[bullet title\]\*\*", re.MULTILINE)
+
+
+def _check_roadmap(root: Path) -> Check:
+    path = root / "project-management/Roadmap/README.md"
+    if not path.exists():
+        return Check(
+            "roadmap",
+            Status.WARN,
+            f"Missing {path.relative_to(root)} — projects without a roadmap will drift.",
+        )
+    content = path.read_text()
+    if _TEMPLATE_BULLET_PATTERN.search(content) and not _ACTIVE_BULLET_PATTERN.search(content):
+        return Check(
+            "roadmap",
+            Status.WARN,
+            "Roadmap still shows the template '#N — [bullet title]'. "
+            "Update Active Bullet when you start work.",
+        )
+    if not _ACTIVE_BULLET_PATTERN.search(content):
+        return Check(
+            "roadmap",
+            Status.WARN,
+            "No Active Bullet line matching '**#N — title**' in Roadmap. "
+            "Set one when starting a bullet.",
+        )
+    return Check("roadmap", Status.OK, "Roadmap has an Active Bullet.")
+
+
+def _check_stale_sessions(root: Path) -> Check:
+    sessions_dir = root / "project-management/Work/sessions"
+    if not sessions_dir.exists():
+        return Check("sessions", Status.OK, "No Work/sessions directory yet.")
+    cutoff = datetime.now(timezone.utc) - STALE_SESSION_AGE
+    stale: list[str] = []
+    for p in sessions_dir.glob("*.md"):
+        mtime = datetime.fromtimestamp(p.stat().st_mtime, tz=timezone.utc)
+        if mtime < cutoff:
+            stale.append(p.name)
+    if stale:
+        names = ", ".join(sorted(stale)[:3]) + ("…" if len(stale) > 3 else "")
+        return Check(
+            "sessions",
+            Status.WARN,
+            f"{len(stale)} session file(s) older than {STALE_SESSION_AGE.days} days ({names}). "
+            "Promote insights to ADRs or delete.",
+        )
+    return Check("sessions", Status.OK, "No stale session files.")
+
+
+def _commit_count(root: Path) -> int | None:
+    """Count commits reachable from HEAD, or ``None`` if not a git repo."""
+    try:
+        out = subprocess.run(
+            ["git", "rev-list", "--count", "HEAD"],
+            cwd=root,
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        return int(out.stdout.strip())
+    except (subprocess.CalledProcessError, FileNotFoundError, ValueError):
+        return None
+
+
+def _check_adr_coverage(root: Path) -> Check:
+    adrs_dir = root / "project-management/ADRs"
+    if not adrs_dir.exists():
+        return Check(
+            "adr-coverage",
+            Status.WARN,
+            "No ADRs directory; `beacon init` should have created one.",
+        )
+    real_adrs = [p for p in adrs_dir.glob("ADR-*.md") if not p.name.startswith("ADR-000-")]
+    commits = _commit_count(root)
+    if commits is None:
+        if real_adrs:
+            return Check(
+                "adr-coverage",
+                Status.OK,
+                f"{len(real_adrs)} ADR(s) on file (git history unavailable for heuristic).",
+            )
+        return Check(
+            "adr-coverage",
+            Status.OK,
+            "No ADRs yet (no git history to weigh against).",
+        )
+    if commits >= ADR_HEURISTIC_COMMITS and not real_adrs:
+        return Check(
+            "adr-coverage",
+            Status.WARN,
+            f"{commits} commits and zero non-template ADRs. "
+            "Significant decisions are probably going unrecorded.",
+        )
+    return Check(
+        "adr-coverage",
+        Status.OK,
+        f"{len(real_adrs)} ADR(s) on file across {commits} commits.",
+    )
+
+
+def _check_framework_drift(root: Path) -> Check:
+    manifest = Manifest.load(root)
+    if manifest is None:
+        # Already surfaced by _check_manifest; don't double-report.
+        return Check("drift", Status.OK, "(skipped — no manifest)")
+    src_root = _resource_root()
+    drifted: list[str] = []
+    missing: list[str] = []
+    for rel in manifest.framework_files:
+        # Skip non-resource files (e.g. anything an integration writes to
+        # paths outside resources/, like .claude/CLAUDE.md whose content is
+        # legitimately user-edited around the BEACON marker block).
+        if rel.startswith(".claude/"):
+            continue
+        src = src_root / rel
+        dst = root / rel
+        if not src.exists():
+            continue
+        if not dst.exists():
+            missing.append(rel)
+            continue
+        if src.read_bytes() != dst.read_bytes():
+            drifted.append(rel)
+    if missing:
+        return Check(
+            "drift",
+            Status.FAIL,
+            f"{len(missing)} framework file(s) missing: {', '.join(missing[:3])}"
+            f"{'…' if len(missing) > 3 else ''}. Run `beacon upgrade`.",
+        )
+    if drifted:
+        return Check(
+            "drift",
+            Status.WARN,
+            f"{len(drifted)} framework file(s) modified on disk: "
+            f"{', '.join(drifted[:3])}{'…' if len(drifted) > 3 else ''}. "
+            "`beacon upgrade` will overwrite them.",
+        )
+    return Check("drift", Status.OK, "Framework files match shipped resources.")
+
+
+CHECKS = (
+    _check_manifest,
+    _check_problem_statement,
+    _check_roadmap,
+    _check_stale_sessions,
+    _check_adr_coverage,
+    _check_framework_drift,
+)
+
+
+def run_all(root: Path) -> list[Check]:
+    return [check(root) for check in CHECKS]
+
+
+def summarise(checks: list[Check], *, strict: bool) -> tuple[int, int, int, int]:
+    """Return (ok, warn, fail, exit_code). Strict promotes WARN to FAIL."""
+    ok = sum(1 for c in checks if c.status is Status.OK)
+    warn = sum(1 for c in checks if c.status is Status.WARN)
+    fail = sum(1 for c in checks if c.status is Status.FAIL)
+    failing = fail + (warn if strict else 0)
+    return ok, warn, fail, 1 if failing else 0

{beacon_framework-0.2.0 → beacon_framework-0.3.0}/src/beacon/integrations/__init__.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from collections.abc import Callable
 from pathlib import Path
 
-from beacon.integrations import claude_code
+from beacon.integrations import claude_code, release
 
 # Each entry exposes (install, remove) callables. Both take ``project_root`` and
 # return the list of relative paths written or removed.
@@ -17,6 +17,7 @@ Integration = tuple[Callable[[Path], list[str]], Callable[[Path], list[str]]]
 
 REGISTRY: dict[str, Integration] = {
     "claude": (claude_code.install, claude_code.remove),
+    "release": (release.install, release.remove),
 }
 
 

beacon_framework-0.3.0/src/beacon/integrations/release.py

@@ -0,0 +1,185 @@
+"""Release-pipeline integration.
+
+Packages the python-semantic-release + PyPI Trusted Publishing setup we
+shipped for beacon itself as a reusable integration. Consumers run:
+
+    beacon integration add release
+
+and get the GitHub Actions workflow, a PUBLISHING.md, and an injected
+``[tool.semantic_release]`` block in their ``pyproject.toml``.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from pathlib import Path
+
+INTEGRATION_NAME = "release"
+RESOURCE_SUBDIR = "integrations/release"
+
+# Files written into the consumer's project. Tuples of (resource-relative
+# path, project-relative destination, framework_or_user_seeded).
+#
+# - framework: always overwritten by install/upgrade (BEACON owns it)
+# - user_seeded: written only if absent (user may edit thereafter)
+_FILES: tuple[tuple[str, str, str], ...] = (
+    ("workflows/release.yml", ".github/workflows/release.yml", "framework"),
+    ("PUBLISHING.md", "PUBLISHING.md", "user_seeded"),
+)
+
+_PSR_CONFIG_NAME = "psr_config.toml"
+"""Resource file containing the [tool.semantic_release] block to merge."""
+
+# Sentinel header used to find and strip the PSR block on `remove`.
+_PSR_HEADER_RE = re.compile(r"^\[tool\.semantic_release(?:\..+)?\]\s*$", re.MULTILINE)
+_PSR_FENCE_START = "# ──── BEACON release integration: python-semantic-release config ────"
+_PSR_FENCE_END = "# ──── end BEACON release integration ────"
+
+
+def _resource_root() -> Path:
+    return Path(str(resources.files("beacon").joinpath("resources").joinpath(RESOURCE_SUBDIR)))
+
+
+def _read_resource(rel: str) -> str:
+    return (_resource_root() / rel).read_text()
+
+
+# ---- pyproject.toml introspection -----------------------------------------
+
+
+def _package_name(project_root: Path) -> str:
+    """Best-effort read of the consumer's package name from pyproject.toml."""
+    pyproject = project_root / "pyproject.toml"
+    if not pyproject.exists():
+        return "your-package"
+    try:
+        import tomllib
+    except ImportError:  # Python < 3.11 — package is 3.10+ but tomllib is 3.11+
+        import tomli as tomllib  # type: ignore[no-redef]
+    try:
+        data = tomllib.loads(pyproject.read_text())
+        return str(data.get("project", {}).get("name") or "your-package")
+    except Exception:
+        return "your-package"
+
+
+def _git_owner_repo(project_root: Path) -> tuple[str, str]:
+    """Best-effort parse of ``OWNER`` and ``REPO`` from ``.git/config``."""
+    cfg = project_root / ".git" / "config"
+    if cfg.exists():
+        m = re.search(
+            r"github\.com[:/]([\w-]+)/([\w.-]+?)(?:\.git)?\s*$", cfg.read_text(), re.MULTILINE
+        )
+        if m:
+            return m.group(1), m.group(2)
+    return "your-org", project_root.name
+
+
+def _render(content: str, project_root: Path) -> str:
+    """Substitute templating tokens before writing into the consumer project."""
+    name = _package_name(project_root)
+    owner, repo = _git_owner_repo(project_root)
+    return (
+        content.replace("{{PACKAGE_NAME}}", name)
+        .replace("{{OWNER}}", owner)
+        .replace("{{REPO}}", repo)
+    )
+
+
+# ---- pyproject.toml merge ------------------------------------------------
+
+
+def _has_psr_config(pyproject_text: str) -> bool:
+    return bool(_PSR_HEADER_RE.search(pyproject_text))
+
+
+def _inject_psr_block(pyproject_text: str, block: str) -> str:
+    """Append the fenced PSR block to the consumer's pyproject content."""
+    fenced = f"\n\n{_PSR_FENCE_START}\n{block.strip()}\n{_PSR_FENCE_END}\n"
+    return pyproject_text.rstrip() + fenced
+
+
+def _strip_psr_block(pyproject_text: str) -> str:
+    """Remove the BEACON-fenced PSR block from pyproject content.
+
+    Only removes content inside the fence sentinels so we never delete a
+    hand-authored PSR config that happens to live in the same file.
+    """
+    pattern = re.compile(
+        r"\n*" + re.escape(_PSR_FENCE_START) + r".*?" + re.escape(_PSR_FENCE_END) + r"\n?",
+        re.DOTALL,
+    )
+    return pattern.sub("\n", pyproject_text).rstrip() + "\n"
+
+
+# ---- install / remove ----------------------------------------------------
+
+
+def install(project_root: Path) -> list[str]:
+    """Install the release pipeline. Returns relpaths written."""
+    written: list[str] = []
+
+    for src_rel, dst_rel, mode in _FILES:
+        dst = project_root / dst_rel
+        if mode == "user_seeded" and dst.exists():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        content = _render(_read_resource(src_rel), project_root)
+        dst.write_text(content)
+        written.append(dst_rel)
+
+    # Inject PSR config into pyproject.toml
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text()
+        if _PSR_FENCE_START in text:
+            # Already installed — refresh the fenced block (framework-owned).
+            text = _strip_psr_block(text)
+            text = _inject_psr_block(text, _read_resource(_PSR_CONFIG_NAME))
+            pyproject.write_text(text)
+            written.append("pyproject.toml")
+        elif _has_psr_config(text):
+            # User has their own PSR config; don't touch it.
+            print(
+                "  ⚠  pyproject.toml already has [tool.semantic_release] — "
+                "leaving it untouched. Reconcile manually if needed."
+            )
+        else:
+            pyproject.write_text(_inject_psr_block(text, _read_resource(_PSR_CONFIG_NAME)))
+            written.append("pyproject.toml")
+    else:
+        # No pyproject.toml in the project — write a stub
+        text = '[project]\nname = "' + _package_name(project_root) + '"\nversion = "0.1.0"\n'
+        pyproject.write_text(_inject_psr_block(text, _read_resource(_PSR_CONFIG_NAME)))
+        written.append("pyproject.toml")
+
+    return written
+
+
+def remove(project_root: Path) -> list[str]:
+    """Remove the release pipeline. Returns relpaths removed/modified."""
+    removed: list[str] = []
+
+    for _, dst_rel, mode in _FILES:
+        if mode != "framework":
+            continue  # leave user_seeded files (e.g. PUBLISHING.md) alone
+        dst = project_root / dst_rel
+        if dst.exists():
+            dst.unlink()
+            removed.append(dst_rel)
+            # Best-effort tidy of empty parents (.github/workflows)
+            for parent in (dst.parent, dst.parent.parent):
+                try:
+                    parent.rmdir()
+                except OSError:
+                    break
+
+    pyproject = project_root / "pyproject.toml"
+    if pyproject.exists():
+        text = pyproject.read_text()
+        if _PSR_FENCE_START in text:
+            pyproject.write_text(_strip_psr_block(text))
+            removed.append("pyproject.toml")
+
+    return removed

beacon_framework-0.3.0/src/beacon/resources/integrations/release/PUBLISHING.md

@@ -0,0 +1,84 @@
+# Publishing `{{PACKAGE_NAME}}`
+
+Releases are automated by [python-semantic-release][psr] + GitHub Actions. The workflow at [`.github/workflows/release.yml`](.github/workflows/release.yml) runs on every push to `main` and `develop`.
+
+| Branch | Channel | Version style | Trigger |
+|---|---|---|---|
+| `main` | [PyPI](https://pypi.org/project/{{PACKAGE_NAME}}/) | `0.2.0`, `0.3.0`, … | merge PR into `main` |
+| `develop` | [TestPyPI](https://test.pypi.org/project/{{PACKAGE_NAME}}/) | `0.2.0-dev.1`, `0.2.0-dev.2`, … | push to `develop` |
+
+## How versions are computed
+
+[python-semantic-release][psr] reads Conventional Commits since the last tag and bumps accordingly:
+
+| Commit prefix | Bump |
+|---|---|
+| `feat:` | minor (0.X.0) |
+| `fix:` / `perf:` | patch (0.X.Y) |
+| Footer contains `BREAKING CHANGE:` | major — **suppressed** while at 0.x (see `major_on_zero = false` in `pyproject.toml`) |
+
+The release workflow:
+
+1. Inspects commits, computes the next version
+2. Updates `pyproject.toml:project.version`
+3. Generates / appends to `CHANGELOG.md`
+4. Commits the bump (`chore(release): X.Y.Z`)
+5. Tags `vX.Y.Z`
+6. Builds wheel + sdist with `uv build`
+7. Publishes to PyPI (main) or TestPyPI (develop)
+8. Creates a GitHub Release and attaches the dists
+
+## One-time setup (you must do this once before the first release)
+
+### 1. Reserve the package name with PyPI Trusted Publishing (OIDC)
+
+PyPI Trusted Publishing means no long-lived API tokens — GitHub Actions authenticates to PyPI via short-lived OIDC tokens scoped to a specific workflow + environment.
+
+**PyPI** — https://pypi.org/manage/account/publishing/ → *Add a new pending publisher*:
+
+| Field | Value |
+|---|---|
+| PyPI project name | `{{PACKAGE_NAME}}` |
+| Owner | `{{OWNER}}` |
+| Repository name | `{{REPO}}` |
+| Workflow filename | `release.yml` |
+| Environment name | `pypi` |
+
+**TestPyPI** — https://test.pypi.org/manage/account/publishing/ → same form:
+
+| Field | Value |
+|---|---|
+| PyPI project name | `{{PACKAGE_NAME}}` |
+| Owner | `{{OWNER}}` |
+| Repository name | `{{REPO}}` |
+| Workflow filename | `release.yml` |
+| Environment name | `testpypi` |
+
+Both stay "pending" until the first publish, which claims the name on each index.
+
+### 2. Create the matching GitHub environments
+
+In this repo's settings → *Environments* → *New environment*, create two:
+
+- `pypi` — optionally add a *Required reviewers* protection rule so a human approves each PyPI publish.
+- `testpypi` — typically no protection rules (it is the canary).
+
+### 3. Create the `develop` branch
+
+```bash
+git checkout main
+git pull
+git checkout -b develop
+git push -u origin develop
+```
+
+Feature branches → PR into `develop` (→ TestPyPI on merge), `develop` → PR into `main` (→ PyPI on merge).
+
+## Verifying a release
+
+```bash
+uvx --from {{PACKAGE_NAME}} <your-cli> --version                                              # stable
+uvx --index-url https://test.pypi.org/simple/ --from {{PACKAGE_NAME}} <your-cli> --version    # pre-release
+```
+
+[psr]: https://python-semantic-release.readthedocs.io/

beacon_framework-0.3.0/src/beacon/resources/integrations/release/psr_config.toml

@@ -0,0 +1,37 @@
+# ──────────────────────────────────────────────────────────────────────
+# Release automation — python-semantic-release reads Conventional Commits
+# (feat → minor, fix/perf → patch, BREAKING CHANGE → major). Pushes to
+# `main` produce stable releases on PyPI; pushes to `develop` produce
+# pre-releases (e.g. 0.2.0-dev.1) on TestPyPI. See PUBLISHING.md for the
+# one-time PyPI/TestPyPI Trusted Publisher setup.
+# Installed by `beacon integration add release`.
+# ──────────────────────────────────────────────────────────────────────
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+# If you maintain a `__version__` string in your package, add it here too:
+# version_variables = ["src/<your_package>/__init__.py:__version__"]
+build_command = "python -m pip install --quiet uv && uv build"
+major_on_zero = false        # stay in 0.x until v1 is explicit
+allow_zero_version = true    # permit 0.x line
+commit_parser = "conventional"
+
+[tool.semantic_release.commit_parser_options]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+allowed_tags = [
+    "feat", "fix", "perf", "refactor", "docs",
+    "test", "chore", "ci", "build", "style", "revert",
+]
+
+[tool.semantic_release.branches.main]
+match = "^main$"
+prerelease = false
+
+[tool.semantic_release.branches.develop]
+match = "^develop$"
+prerelease = true
+prerelease_token = "dev"     # → 0.2.0-dev.1, 0.2.0-dev.2, …
+
+[tool.semantic_release.changelog]
+exclude_commit_patterns = ["^chore\\(release\\):"]

beacon_framework-0.3.0/src/beacon/resources/integrations/release/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+# Branch → distribution channel:
+#   main    → PyPI       (stable releases)
+#   develop → TestPyPI   (pre-releases, e.g. 0.2.0-dev.1)
+#
+# Versioning is driven by python-semantic-release reading Conventional
+# Commits since the last tag:
+#   feat:           → minor bump
+#   fix:, perf:     → patch bump
+#   BREAKING CHANGE → major bump (suppressed while at 0.x — see pyproject)
+#
+# Both PyPI and TestPyPI use Trusted Publishing (OIDC) — no API tokens.
+# One-time setup is in PUBLISHING.md.
+
+on:
+  push:
+    branches: [main, develop]
+  workflow_dispatch:
+
+# Never run two releases at once on the same branch — they would race on
+# tags and dist files.
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write   # required: PSR pushes the version-bump commit and creates the tag/release
+  id-token: write   # required: OIDC token for PyPI / TestPyPI trusted publishing
+
+jobs:
+  release:
+    name: Release ${{ github.ref_name == 'main' && 'to PyPI' || 'pre-release to TestPyPI' }}
+    runs-on: ubuntu-latest
+    environment:
+      name: ${{ github.ref_name == 'main' && 'pypi' || 'testpypi' }}
+      url: ${{ github.ref_name == 'main' && format('https://pypi.org/project/{0}/', '{{PACKAGE_NAME}}') || format('https://test.pypi.org/project/{0}/', '{{PACKAGE_NAME}}') }}
+
+    steps:
+      - name: Check out (full history for semantic-release commit analysis)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Python Semantic Release
+        id: psr
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        if: steps.psr.outputs.released == 'true' && github.ref_name == 'main'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Publish pre-release to TestPyPI
+        if: steps.psr.outputs.released == 'true' && github.ref_name == 'develop'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+      - name: Attach distributions to GitHub Release
+        if: steps.psr.outputs.released == 'true'
+        uses: python-semantic-release/publish-action@v9
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ steps.psr.outputs.tag }}