diff --git a/CLAUDE.md b/CLAUDE.md index bfbc697..653bc12 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -77,7 +77,7 @@ The `templates/` collection in `~/Projects/agents/templates/` is the influence l ## Working in this repo 1. **Run all commands from the repo root.** `bun install`, `bun test`, `bun run dev `, `bun run build:binary`. -2. **Branches:** `main` only on tagged releases. Feature branches: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`. Conventional commit messages. +2. **Branching is trunk-based (Option A, locked 2026-05-29).** `main` is the protected trunk and the only long-lived branch. Every change lands via a short-lived branch -> PR -> green CI -> **squash-merge** -> head branch auto-deletes (merge-commit and rebase-merge are disabled). Prefixes: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`, `chore/`, with a kebab-case slug after the slash, optionally issue-scoped (`fix/123-worktree-reset`). One branch = one PR = one squashed conventional commit = one concern; branch from latest `main` (`git fetch origin && git switch -c feat/ origin/main`), never from another topic branch; never push `worktree-*` scratch branches. Releases are annotated SemVer tags (`vX.Y.Z-alpha.N`) on a green `main`, cut behind a `chore/release-*` PR. `main` is protected for everyone including admins (required `bun test` checks, linear history, no force-push or deletion, PR-before-merge). Full contract: CONTRIBUTING.md § "Branching and merge workflow". 3. **Tests must run offline.** Spine tests use `FakeProvider`. Live-provider tests are opt-in only and gated behind env flags. 4. **No emojis in code or commit messages.** No "Co-Authored-By: Claude" footers unless asked. 5. **Never push to GitHub without explicit user approval.** Local commits are fine. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d5255d..23bf082 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ Requirements: - **Node 18 or newer** for the npm wrapper smoke (`node --version`). - macOS arm64, macOS x64, Linux x64, or Linux arm64. Windows local development is not currently supported (the npm wrapper and binaries are Unix-only). -The full offline test suite runs in under 30 seconds on a recent machine and should report `3395 pass / 0 fail / 2 skip` against `main`. The two skipped tests are the opt-in live-provider tests described below. +The full offline test suite runs in under 30 seconds on a recent machine and should report `3750+ pass / 0 fail` against `main` (the pass count grows as suites are added; the 2 skipped tests are the opt-in live-provider tests described below). ## Test discipline @@ -78,15 +78,21 @@ Common scopes: `readme`, `providers`, `gates`, `cli`, `demo`, `package`, the mil - **No squash-commit messages with raw model output.** Edit the message before committing. - **No secret material** (API keys, tokens, customer data, internal hostnames) anywhere in the diff or message. -### Branch naming +### Branching and merge workflow -- `feat/-` for new features -- `fix/-` for bug fixes -- `refactor/-` for refactors -- `docs/-` for docs-only changes -- `test/-` for test-only additions +The repo is **trunk-based** (locked 2026-05-29). `main` is the protected trunk; everything else is a short-lived branch. -`main` is tag-only. Pushes to `main` happen at release time. +- Branch from the latest `main`: `git fetch origin && git switch -c feat/ origin/main`. Never branch from another topic branch. +- Prefixes: `feat/`, `fix/`, `refactor/`, `test/`, `docs/`, `chore/`. After the slash, a short kebab-case slug, optionally issue-scoped: `fix/123-worktree-reset-on-restart`. +- One branch = one PR = one concern. If a branch grows a second concern, cut a second branch. +- Open the PR the same session and keep branches short-lived. On merge the branch **auto-deletes** — do not delete it by hand. +- Never push `worktree-*` scratch branches; git worktrees stay local. + +**Merging.** PRs **squash-merge** into `main` (merge commits and rebase-merge are disabled), so one PR becomes exactly one conventional commit on `main`. The PR title is the squash commit subject, so it must be Conventional-Commit form. + +**`main` is protected.** Required status checks (`bun test on ubuntu-latest`, `bun test on macos-latest`), strict/up-to-date, linear history, no force-push, no deletion, PR-before-merge — enforced for everyone including admins. There are no direct pushes to `main`. + +**Releases.** Annotated SemVer tags (`vX.Y.Z-alpha.N`) on a green `main` commit, cut behind a `chore/release-*` PR (version bump + CHANGELOG) so the bump itself passes CI. One tag per release; tags are never moved. ## Pull request expectations @@ -121,7 +127,7 @@ When adding a new provider adapter or modifying an existing one: - A maintainer triages within a few days. Triage adds labels and may ask for clarification. - Substantive PRs get a Codex review pass (see above). The review verdict is recorded in the PR conversation. - Block-push findings close in a follow-up commit on the PR branch before merge. -- The merge strategy is squash-merge to `finalize/` branches or rebase to feature branches. `main` only receives release tags. +- The merge strategy is **squash-merge into `main`**; the head branch auto-deletes on merge. Release tags are cut on `main` behind a `chore/release-*` PR (see "Branching and merge workflow"). ## Code of conduct