feat: enforce issue-linked branches + versioning/tagging policy (#48) #49

2026-07-02T02:42:23-05:00

jcwalker3 commented

2026-07-02 02:42:23 -05:00

Closes #48. Refs #38, #39, #46.

Branch ↔ issue linkage (enforced)

scripts/worktree-start now validates branch names:
- implementation: (fix|feat|docs|chore)/issue-<number>-<slug>
- review: review/pr-<number>-<slug>
- untraceable names → clear error, exit 2; --allow-unlinked overrides; --dry-run preserved.
Documented issue → branch → worktree → PR → cleanup traceability (runbook table + portable SKILL), the claim-comment convention (Claimed. Branch: … Worktree: …), and Closes #n vs Refs #n in PR bodies.
Gitea API note: no native issue→branch field (only a PR's head branch), so linkage is enforced by branch name + claim comment + PR body + cleanup — documented, no API change.

Versioning / tagging policy (docs only)

SemVer vMAJOR.MINOR.PATCH (v0.x.y while unstable); PATCH/MINOR/MAJOR bump rules.
Tags: annotated only, from the exact commit on remote master, only after the full suite passes, with release notes referencing merged PRs/issues. Never tag feature branches, dirty worktrees, unreviewed/self-authored work, or commits not on remote master.
Release runbook (runbook + SKILL) + new template skills/llm-project-workflow/templates/release-tag.md.
Release-automation script deferred to a later issue (kept this diff narrow/testable per the task's option to document now, automate later).

Tests / checks

worktree-start validation tests: accepts fix|feat|docs|chore/issue-123-… + review/pr-456-…; rejects fix/random-name, my-branch, non-numeric issue; honors --allow-unlinked; preserves --dry-run. (Existing refuse-overwrite test updated to an issue-linked name.)
Full suite (isolated worktree): 291 passed, 0 failures, 0 errors (JUnit XML).
bash -n clean; git diff --check clean; secret scan of script/docs clean.

Files changed

scripts/worktree-start, tests/test_worktrees.py, docs/llm-workflow-runbooks.md, skills/llm-project-workflow/SKILL.md, skills/llm-project-workflow/templates/release-tag.md (new).

Process

Isolated worktree: ./scripts/worktree-start feat/issue-48-branch-release-standards → branches/feat-issue-48-branch-release-standards.

⚠️ Authored by me — do not self-merge. Needs review by another author.

Closes #48. Refs #38, #39, #46. ## Branch ↔ issue linkage (enforced) - `scripts/worktree-start` now **validates** branch names: - implementation: `(fix|feat|docs|chore)/issue-<number>-<slug>` - review: `review/pr-<number>-<slug>` - untraceable names → clear error, **exit 2**; `--allow-unlinked` overrides; `--dry-run` preserved. - Documented **issue → branch → worktree → PR → cleanup** traceability (runbook table + portable SKILL), the claim-comment convention (`Claimed. Branch: … Worktree: …`), and `Closes #n` vs `Refs #n` in PR bodies. - **Gitea API note:** no native issue→branch field (only a PR's head branch), so linkage is enforced by branch name + claim comment + PR body + cleanup — documented, no API change. ## Versioning / tagging policy (docs only) - SemVer `vMAJOR.MINOR.PATCH` (`v0.x.y` while unstable); PATCH/MINOR/MAJOR bump rules. - Tags: **annotated only**, from the exact commit on remote `master`, only after the full suite passes, with release notes referencing merged PRs/issues. **Never tag** feature branches, dirty worktrees, unreviewed/self-authored work, or commits not on remote `master`. - Release runbook (runbook + SKILL) + new template `skills/llm-project-workflow/templates/release-tag.md`. - **Release-automation script deferred** to a later issue (kept this diff narrow/testable per the task's option to document now, automate later). ## Tests / checks - `worktree-start` validation tests: accepts `fix|feat|docs|chore/issue-123-…` + `review/pr-456-…`; rejects `fix/random-name`, `my-branch`, non-numeric issue; honors `--allow-unlinked`; preserves `--dry-run`. (Existing refuse-overwrite test updated to an issue-linked name.) - Full suite (isolated worktree): **291 passed, 0 failures, 0 errors** (JUnit XML). - `bash -n` clean; `git diff --check` clean; secret scan of script/docs clean. ## Files changed `scripts/worktree-start`, `tests/test_worktrees.py`, `docs/llm-workflow-runbooks.md`, `skills/llm-project-workflow/SKILL.md`, `skills/llm-project-workflow/templates/release-tag.md` (new). ## Process Isolated worktree: `./scripts/worktree-start feat/issue-48-branch-release-standards` → `branches/feat-issue-48-branch-release-standards`. --- ⚠️ Authored by me — do **not** self-merge. Needs review by another author.

jcwalker3 added 1 commit 2026-07-02 02:42:23 -05:00

feat: enforce issue-linked branches + document versioning/tagging policy (#48 ) 8bff54d5ac

Formalize the branch↔issue relationship and add a release/version-tagging policy.

Branch/issue linkage:
- scripts/worktree-start now validates branch names: implementation branches
  must match (fix|feat|docs|chore)/issue-<number>-<slug>; review branches
  review/pr-<number>-<slug>. Untraceable names are rejected with a clear error
  (exit 2). New --allow-unlinked override for genuine exceptions. --dry-run
  preserved.
- Documented issue → branch → worktree → PR → cleanup traceability in the
  runbook and the portable SKILL, including the claim-comment convention and
  Closes #n / Refs #n PR-body usage.
- Noted that Gitea exposes no native issue→branch API field (only a PR head
  branch), so linkage is enforced via branch name + claim comment + PR body +
  cleanup.

Versioning / tagging policy (docs only; no release automation yet):
- SemVer vMAJOR.MINOR.PATCH (v0.x.y while unstable) with PATCH/MINOR/MAJOR bump
  rules.
- Annotated tags only, from the exact commit on remote master, only after the
  full suite passes, with release notes referencing merged PRs/issues. Never tag
  feature branches, dirty worktrees, unreviewed/self-authored work, or commits
  not on remote master.
- Release runbook in the runbook + SKILL, plus a new
  skills/llm-project-workflow/templates/release-tag.md prompt template.

Tests: worktree-start branch validation — accepts fix/feat/docs/chore/issue-*
and review/pr-*, rejects fix/random-name / my-branch / non-numeric issue,
honors --allow-unlinked, preserves --dry-run. Full suite 291 passed / 0 failures;
bash -n clean; git diff --check clean; no secrets.

Release-tag automation (a scripts/release-tag helper) intentionally deferred to a
later issue to keep this diff narrow and testable.

Closes #48. Refs #38, #39, #46.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>