ci: enable develop branch workflow

.github/pull_request_template.md

@@ -10,6 +10,7 @@ See here for instructions: https://docs.github.com/en/authentication/managing-co
 
 <!--
 Please provide a clear and concise description of what the changes are, and why they are needed.
+The completed Description section must contain at least 20 characters.
 Include a link to the issue this PR addresses, if applicable (e.g. "Closes #123").
 -->
 
@@ -20,16 +21,20 @@ Please describe the tests you've performed to verify your changes.
 Include relevant code samples, unit test cases, or screenshots if applicable.
 
 For TypeScript: Run `pnpm test` from the `/typescript` directory
-For Python: Run `uv run pytest` from the `/python/x402` directory
 -->
 
+## Branch route
+
+- [ ] Normal development targets `develop`
+- [ ] Only `release_*` or `hotfix/*` targets `main`
+
 ## Checklist
 
 - [ ] I have formatted and linted my code
 - [ ] All new and existing tests pass
+- [ ] I added a Changeset for publishable package changes, or this PR does not require one
 - [ ] My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits
 
 <!--
 For TypeScript: Run `pnpm lint` from `/typescript`
-For Python: Run `uvx ruff check && uvx ruff format --check` from `/python/x402`
 -->

.github/workflows/audit-pr.yml

@@ -3,6 +3,7 @@ name: Audit PR
 on:
   pull_request:
     branches:
+      - develop
       - main
     types: [opened, synchronize, reopened, ready_for_review]
   issue_comment:

.github/workflows/branch-policy.yml

@@ -0,0 +1,21 @@
+name: Validate branch policy
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, edited]
+
+permissions:
+  contents: read
+
+jobs:
+  source-and-target:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - name: Validate pull request route
+        run: sh scripts/check_branch_policy.sh "${{ github.base_ref }}" "${{ github.head_ref }}"

.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: TypeScript CI
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: typescript-ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  typescript-quality:
+    name: TypeScript quality
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: typescript
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.1.1
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: typescript/pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Check lint
+        run: pnpm lint:check
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run unit tests
+        run: pnpm test

.github/workflows/policy-tests.yml

@@ -0,0 +1,25 @@
+name: Test policy validators
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  policy-tests:
+    name: Policy validator tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Test branch policy
+        run: sh scripts/check_branch_policy.test.sh
+      - name: Test pull request metadata policy
+        run: node --test scripts/check_pr_metadata.test.mjs

.github/workflows/pr-metadata.yml

@@ -0,0 +1,25 @@
+name: Validate PR metadata
+
+on:
+  pull_request:
+    branches:
+      - develop
+      - main
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  pr-metadata:
+    name: PR metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+      - name: Validate title and description
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: node scripts/check_pr_metadata.mjs

BRANCHING.md

@@ -0,0 +1,62 @@
+# Branching and Release Policy
+
+This repository uses a two-branch development model based on java-tron's release workflow.
+
+## Long-lived branches
+
+- `develop` is the default development and integration branch. Start normal work from `develop`
+  and merge it back through a pull request.
+- `main` contains stable, released code. Do not send feature, fix, documentation, or upstream-sync
+  pull requests directly to `main`.
+
+Protect both branches from direct pushes, force pushes, and deletion. Require pull requests,
+successful checks, review approval, and resolved conversations before merging.
+
+## Development branches
+
+Create day-to-day branches from `develop`. Supported prefixes are:
+
+- `feature/*` or `feat/*` for features
+- `fix/*` for non-release fixes
+- `docs/*`, `chore/*`, `refactor/*`, `test/*`, `perf/*`, or `ci/*` for their corresponding work
+- `sync/*` for upstream synchronization
+
+Open these pull requests against `develop`.
+
+## Release branches
+
+When `develop` is ready for release:
+
+1. Create `release_vX.Y.Z` from `develop`.
+2. Apply version changes, consume Changesets, update release notes, and complete regression testing
+   on the release branch.
+3. If regression identifies a bug, merge its fix directly into the release branch and repeat the
+   regression test.
+4. Open `release_vX.Y.Z` into `main` and merge it with a merge commit.
+5. Tag and publish from the resulting `main` commit.
+6. Merge the release branch back into `develop` after the release passes regression.
+7. Retain the release branch permanently as the release snapshot.
+
+Release branches must use the `release_*` pattern. Never open `develop` directly into `main`.
+
+## Hotfix branches
+
+For an urgent production fix:
+
+1. Create `hotfix/<description>` from `main`.
+2. Open it into `main`, complete review and CI, and merge it with a merge commit.
+3. Merge the same hotfix branch into `develop`.
+
+Retain the hotfix branch until both merges are complete.
+
+## Allowed pull request routes
+
+| Source | Target | Purpose |
+| --- | --- | --- |
+| Development branch | `develop` | Normal development |
+| `release_*` | `main` | Stable release |
+| `release_*` | `develop` | Mandatory release back-merge |
+| `hotfix/*` | `main` | Production hotfix |
+| `hotfix/*` | `develop` | Hotfix back-merge |
+
+The `source-and-target` workflow enforces these routes.

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Changed
+
+- Adopted `develop` as the integration branch and retained `main` for stable releases.
+- Added enforced pull request routes for development, release, and hotfix branches.
+- Added automated pull request title and description validation.
+- Added pull request CI for policy tests, formatting, linting, build, and unit tests.
+
 ## [1.1.0] - 2026-08-25
 
 ### Upgrade notes

CLAUDE.md

@@ -42,6 +42,15 @@ Each component has its own `CLAUDE.md` (where present) with build/test commands
 - **Mechanism registration**: `tron:0xcd8690dc` (exact match, higher priority) beats `tron:*` (wildcard, lower priority).
 - **Commit messages**: `<type>(<scope>): <description>` — e.g. `fix(tron): preserve raw_data_hex in tron approvals`.
 
+## Branch workflow
+
+- Start normal development, documentation, maintenance, and upstream-sync branches from `develop`
+  and open them back to `develop`.
+- Treat `main` as stable release history. Only `release_*` and `hotfix/*` branches may target
+  `main`.
+- Never open `develop` directly into `main`.
+- Follow [BRANCHING.md](BRANCHING.md) for release back-merges, hotfixes, and branch retention.
+
 ## AI-native development
 
 This repo uses a Claude-Code-native layout: rules, commands, and agents that let Claude (and other agents following the same conventions) contribute safely without reading every file first.

CONTRIBUTING.md

@@ -26,17 +26,27 @@ By participating in this project, you agree to abide by our Code of Conduct. We
 
 - Fill in the required template (if available).
 - Do not include more than one fix/feature per pull request.
+- Start normal work from `develop` and open the pull request back to `develop`.
+- Use `release_*` or `hotfix/*` branches for pull requests to `main`; never merge `develop`
+  directly into `main`.
 - Ensure that the tests pass and the code adheres to the project's coding standards.
 - Update the documentation if you've made changes to the API or added new features.
 - Commit messages follow `<type>(<scope>): <description>` (see [.claude/rules/common/conventions.md](.claude/rules/common/conventions.md)).
+- PR titles must use `type(scope): description`, contain 10-72 characters, start the description
+  with a lowercase letter or number, and not end with a period. Allowed types are `feat`, `fix`,
+  `refactor`, `docs`, `style`, `test`, `chore`, `ci`, `perf`, `build`, and `revert`.
+- The PR template's Description section must explain what and why in at least 20 characters.
+
+See [BRANCHING.md](BRANCHING.md) for the complete development, release, back-merge, and hotfix
+workflow.
 
 ---
 
 ## Development Setup
 
 ### Prerequisites
 
-- **Node.js**: 20+
+- **Node.js**: 22+
 - **pnpm**: >= 11 (workspace package manager)
 - **A wallet**: a TRON wallet with TRX (Nile/Shasta testnets) and/or a BSC wallet with BNB, for gas.
 

README.md

@@ -201,7 +201,9 @@ Use `pnpm build:release` before `pnpm pack` or `pnpm publish`. The forced build
 
 ## Contributing
 
-We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+We welcome contributions! Start normal work from `develop` and submit it back to `develop`.
+Stable releases reach `main` through a `release_*` branch. See [CONTRIBUTING.md](./CONTRIBUTING.md)
+and [BRANCHING.md](./BRANCHING.md) for the complete workflow.
 
 ## License
 

typescript/.changeset/config.json

@@ -10,7 +10,7 @@
   "fixed": [],
   "linked": [],
   "access": "public",
-  "baseBranch": "main",
+  "baseBranch": "develop",
   "updateInternalDependencies": "patch",
   "ignore": []
 }