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
+29
View File
@@ -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