chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)
ci / gate (push) Successful in 2m5s
ci / manifests (push) Successful in 4s
ci / gate (pull_request) Successful in 2m5s
ci / manifests (pull_request) Successful in 4s

Adopt a trackable working method now the repo is public:
- PRs onto a protected main; --no-ff merge commits; one worktree per branch.
- Reserve-first ADR numbering: scripts/adr-reserve.sh claims the next number
  atomically against main (push = compare-and-swap; ledger
  docs/adr/RESERVATIONS.log), so a number is stable from creation.
- Worktree helpers scripts/wt-new.sh + wt-clean.sh.
- Local-origin test harnesses (reserve 10/10, worktrees 7/7, shellcheck clean).

Record the decision in ADR-0059, supersede ADR-0000's placeholder-until-merge
numbering default, and add the lean CONTRIBUTING.md sections + CLAUDE.md
operational rules.
This commit is contained in:
claude@clouddev1
2026-06-23 20:41:42 +00:00
parent e845a6ee72
commit b5c848efcb
10 changed files with 694 additions and 11 deletions
+16 -11
View File
@@ -45,18 +45,23 @@ ADR numbers are a single global sequence, so two branches can each grab
the `website` branch's ADR-0042 met `main`'s ADR-0042, resolved by
renumbering the former to ADR-0044.) To prevent it:
**Assign an ADR's number at merge-to-`main`, not at creation.** While the
work lives on a non-`main` branch, draft the ADR under a placeholder — an
`ADR-XXXX` title and a `draft-<slug>.md` filename — and reference it that
way from any plan or notes. Give it the next free number only when the
branch merges to `main`, renaming the file and updating its references in
the same step.
**Reserve the number up front, via `scripts/adr-reserve.sh`** (ADR-0059,
which superseded the earlier placeholder-until-merge default). The moment
you know an ADR is needed — at branch start or mid-branch — run
`scripts/adr-reserve.sh <slug> "<title>"`. It atomically claims the next
free number against `main` (the remote ref is the registry; a `git push`
is the compare-and-swap, retried on contention) and records it in the
append-only ledger `docs/adr/RESERVATIONS.log`. The number is then **stable
from creation**, so it is safe to cite in commit messages (immutable under
the no-rewrite rule), in other ADRs, and in the PR from the first commit.
Create the ADR as `docs/adr/<NNNN>-<slug>.md` and add its README index row
as part of the branch's normal work.
A number is "taken" only once it appears in `main`'s `docs/adr/README.md`,
which is the single source of truth for the next free number — never
compute "next" from a feature branch. A branch that genuinely needs a real
number up front may instead reserve one by landing a stub index entry on
`main` first, but placeholder-until-merge is the default.
A number is "taken" once its ledger line (or `NNNN-*.md` file) is on
`main`; the script reads both to compute the next free number — never
compute "next" by hand from a feature branch. The full rationale (why
reserve-first beats number-on-merge, issue-number ids, or an allocator bot)
is in **ADR-0059**.
### Subproject ADR namespaces