chore(workflow): branch-and-PR working method + ADR-number reservation (ADR-0059)
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:
@@ -272,6 +272,35 @@ Key invariants in the code:
|
||||
`git commit` is preceded by an explicit message proposal
|
||||
and user approval. No AI attribution in commit messages.
|
||||
|
||||
## Branch-and-PR working method (ADR-0059)
|
||||
|
||||
The trackable working method for the now-public repo. Full rationale +
|
||||
forks in **ADR-0059**; the public-facing subset is `CONTRIBUTING.md`. The
|
||||
operational rules an agent must follow:
|
||||
|
||||
- **Everything lands via a PR onto a protected `main`.** No direct pushes
|
||||
to `main` (one exception: the ADR-reservation ledger line, D4/D5). One
|
||||
logical change per branch; conventional prefixes (`feat/ fix/ docs/
|
||||
chore/ refactor/ test/ ci/`) matching the commit type.
|
||||
- **One worktree per branch — never switch the primary checkout.** Start a
|
||||
branch with `scripts/wt-new.sh <branch>` (creates branch off `origin/main`
|
||||
+ a sibling `<repo>-worktree-<segment>` worktree); tidy merged ones with
|
||||
`scripts/wt-clean.sh`. This prevents the same-directory clobber hazard.
|
||||
- **Reserve ADR numbers up front** the moment an ADR is known to be needed
|
||||
(branch start *or* mid-branch): `scripts/adr-reserve.sh <slug> "<title>"`
|
||||
atomically claims the next number against `main` (ledger
|
||||
`docs/adr/RESERVATIONS.log`; push = compare-and-swap, retried). The
|
||||
number is stable from creation — cite it freely in commits/cross-refs.
|
||||
**The human runs this script** (its push must originate from them);
|
||||
agents write/test it but don't run its pushing path. Then create
|
||||
`docs/adr/<NNNN>-<slug>.md` + its README index row as normal branch work.
|
||||
- **Merge with `--no-ff` merge commits; never rebase or squash** (append-
|
||||
only history). Push and merge are **human steps** — agents prepare
|
||||
branches, edits, PR text, and commit-message proposals, but never push
|
||||
or merge.
|
||||
- **Paste the `/runda` / DA review into the PR** so the public repo carries
|
||||
the audit trail.
|
||||
|
||||
## Issue tracking — Gitea via `tea`
|
||||
|
||||
Extends (does not replace) the generic Gitea/`tea` safety rules in
|
||||
|
||||
Reference in New Issue
Block a user