ci(governance): land iteration 03 governance foundation (M0-M5)

.github/CODEOWNERS

@@ -0,0 +1,28 @@
+# Default owner: single maintainer until a second maintainer is confirmed (decision gate D3).
+# All paths below are explicit for auditability; they intentionally overlap with the default rule.
+# Syntax reference: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Governance and automation
+/.github/                    @cloudQuant
+/.github/CODEOWNERS          @cloudQuant
+/scripts/                    @cloudQuant
+/docs/governance/            @cloudQuant
+
+# Core package surfaces (risk:r2 per docs/governance/branch-model.md)
+/bt_api_py/bt_api.py         @cloudQuant
+/bt_api_py/containers/       @cloudQuant
+/bt_api_py/feeds/            @cloudQuant
+/bt_api_py/gateway/          @cloudQuant
+/bt_api_py/websocket/        @cloudQuant
+/bt_api_py/forwarding/       @cloudQuant
+/bt_api_py/ctp/              @cloudQuant
+
+# Packaging, submodules, and release path (risk:r3)
+/pyproject.toml              @cloudQuant
+/setup.py                    @cloudQuant
+/.gitmodules                 @cloudQuant
+/.github/workflows/publish.yml      @cloudQuant
+/.github/workflows/submodule-tests.yml @cloudQuant
+
+# Documentation
+/docs/                       @cloudQuant

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,70 @@
+name: Bug Report
+description: 报告 bt_api_py 的缺陷 / Report a defect in bt_api_py
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢报告问题。**请不要在任何字段中粘贴 API 密钥、账户信息或订单数据。**
+        安全漏洞请勿使用此表单，见 [SECURITY.md](https://github.com/cloudQuant/bt_api_py/blob/master/SECURITY.md)。
+  - type: input
+    id: version
+    attributes:
+      label: 版本 / Version
+      description: bt_api_py 版本或 commit SHA
+      placeholder: "0.15.x 或 commit SHA"
+    validations:
+      required: true
+  - type: dropdown
+    id: exchange
+    attributes:
+      label: 涉及模块或交易所 / Affected module or exchange
+      options:
+        - BINANCE
+        - OKX
+        - HTX
+        - CTP
+        - IB (Interactive Brokers)
+        - 其他交易所 / Other exchange（请在描述中注明）
+        - 核心框架（BtApi/containers/feeds 基类）
+        - gateway / websocket
+        - forwarding（MarketDataHub/OrderRouter/Zmq）
+        - 安装/打包/文档
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: 环境 / Environment
+      description: 操作系统、Python 版本、安装方式（PyPI/源码）
+      placeholder: "macOS 15, Python 3.11.9, pip install bt_api_py"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: 最小复现 / Minimal reproduction
+      description: 可运行的最小代码；凭据用占位符
+      placeholder: |
+        from bt_api_py import BtApi
+        # ... 复现步骤
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 预期行为 / Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为 / Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: 日志 / Logs
+      description: 脱敏后的错误日志或堆栈
+      render: shell

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 在线文档 / Documentation
+    url: https://cloudquant.github.io/bt_api_py/
+    about: 安装、快速开始、各交易所指南与 API 参考
+  - name: 安全漏洞 / Security vulnerabilities
+    url: https://github.com/cloudQuant/bt_api_py/blob/master/SECURITY.md
+    about: 请勿公开提交安全问题；按 SECURITY.md 的私密通道报告
+  - name: 邮件联系 / Email
+    url: mailto:yunjinqi@gmail.com
+    about: 私密事项或安全问题的备用通道

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,46 @@
+name: Feature Request
+description: 提议新功能或改进 / Propose a feature or improvement
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        提议前请先搜索既有 issue。**不要粘贴任何凭据。**
+  - type: textarea
+    id: problem
+    attributes:
+      label: 问题场景 / Problem
+      description: 你想解决什么问题？当前方案的痛点是什么？
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: 涉及领域 / Area
+      options:
+        - 新交易所支持 / New exchange support
+        - 已有交易所增强 / Existing exchange enhancement
+        - 核心框架 API
+        - forwarding / 网关
+        - 回测 / 数据
+        - 文档 / 示例
+        - 打包 / CI
+        - 其他
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: 期望方案 / Proposed solution
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 替代方案 / Alternatives considered
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: 贡献意愿 / Willingness to contribute
+      options:
+        - label: 我愿意提交 PR 实现该功能（目标分支 dev）

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,20 @@
+name: Question
+description: 使用问题咨询 / Usage question
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        使用问题请优先查阅[在线文档](https://cloudquant.github.io/bt_api_py/)。
+        **不要粘贴 API 密钥或账户信息。**
+  - type: textarea
+    id: question
+    attributes:
+      label: 你的问题 / Your question
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: 相关上下文 / Context
+      description: 已尝试的方案、相关文档章节、版本与环境信息

.github/governance/labels.yml

@@ -0,0 +1,88 @@
+# Governance label definitions (plan M3 step 4).
+# Labels are maintained by triage maintainers; they are NOT native Ruleset
+# functionality and are enforced by the PR Governance workflow instead.
+labels:
+  # Target branch routing
+  - name: "target:dev"
+    color: "0e8a16"
+    description: "常规贡献目标分支 dev"
+  - name: "target:optimization"
+    color: "1d76db"
+    description: "性能/架构优化线 code-optimization"
+  - name: "target:master"
+    color: "d93f0b"
+    description: "master promotion 或 hotfix"
+  - name: "target:master-hotfix"
+    color: "b60205"
+    description: "master hotfix（需最小复现与回归测试）"
+
+  # Risk levels (docs/governance/branch-model.md §4)
+  - name: "risk:r0"
+    color: "c2e0c6"
+    description: "文档/测试，非行为性变更"
+  - name: "risk:r1"
+    color: "bfd4f2"
+    description: "常规模块变更"
+  - name: "risk:r2"
+    color: "fbca04"
+    description: "核心接口/兼容性变更（BtApi、基类、gateway/websocket/forwarding、CTP）"
+  - name: "risk:r3"
+    color: "e11d48"
+    description: "发布/安全/供应链风险"
+
+  # Release flow
+  - name: "release:hotfix"
+    color: "5319e7"
+    description: "master hotfix 证据已核验"
+
+  # Area
+  - name: "area:core"
+    color: "ededed"
+    description: "BtApi 门面与 containers 基础类型"
+  - name: "area:feeds"
+    color: "ededed"
+    description: "交易所 feed 实现"
+  - name: "area:forwarding"
+    color: "ededed"
+    description: "行情转发与订单路由网关"
+  - name: "area:gateway"
+    color: "ededed"
+    description: "REST 网关与限流"
+  - name: "area:websocket"
+    color: "ededed"
+    description: "WebSocket 连接层"
+  - name: "area:ctp"
+    color: "ededed"
+    description: "CTP 期货接入"
+  - name: "area:docs"
+    color: "ededed"
+    description: "文档与示例"
+  - name: "area:ci"
+    color: "ededed"
+    description: "CI / 构建 / 发布自动化"
+  - name: "area:plugins"
+    color: "ededed"
+    description: "bt_api_* 子模块插件协同"
+
+  # Status / triage
+  - name: "status:needs-triage"
+    color: "f9d0c4"
+    description: "等待分诊确认目标分支与风险级别"
+  - name: "status:needs-repro"
+    color: "f9d0c4"
+    description: "缺少最小复现"
+  - name: "status:needs-tests"
+    color: "f9d0c4"
+    description: "缺少回归测试或测试证据"
+  - name: "status:blocked"
+    color: "eeeeee"
+    description: "被决策门或外部依赖阻塞"
+  - name: "status:ready-to-merge"
+    color: "0e8a16"
+    description: "全部门禁通过，可合并"
+  - name: "sha-bump-required"
+    color: "00b8d9"
+    description: "插件仓已合并，主仓需要 SHA bump PR"
+  - name: "forward-port-required"
+    color: "00b8d9"
+    description: "master hotfix 需在 1 个工作日内前移到 dev"

.github/governance/required-checks.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "Stable check-run names that may be marked required in branch Rulesets. A name is added here ONLY after it has been observed on draft PRs across applicable AND not-applicable paths (plan section 4.2.3).",
+  "dev": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "master": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "code-optimization": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "last_verified": "2026-08-23"
+}

.github/governance/rulesets/code-optimization.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Expected Ruleset state for branch code-optimization (performance/architecture line). Selective PRs only; never merged whole into master. Per plan v2 (§4.2.4, M3 step 6) the ruleset stays DISABLED until M6 draft-PR drills confirm stable summaries; admin flips remote + this manifest together after evidence lands in docs/governance/evidence/.",
+  "target": "code-optimization",
+  "enforcement": "disabled",
+  "activation_requires": "M6 five-scenario draft-PR drill evidence with stable summaries (docs/governance/evidence/)",
+  "pull_request_required": true,
+  "approvals_required": 1,
+  "dismiss_stale_reviews": false,
+  "require_code_owner_review": false,
+  "block_force_pushes": true,
+  "block_deletions": true,
+  "bypass_actors": [],
+  "required_checks": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "last_verified": "2026-08-23"
+}

.github/governance/rulesets/dev.json

@@ -0,0 +1,18 @@
+{
+  "$comment": "Expected Ruleset state for branch dev. Per plan v2 (§4.2.4, M3 step 6, M4 step 8) the ruleset stays DISABLED during the observation period: PR Governance runs report-only and the five M4 draft-PR drills must produce stable summaries on applicable AND not-applicable paths first. Admin flips remote + this manifest to active only after M6 evidence lands in docs/governance/evidence/ (see docs/governance/decision-log.md D0/D3). CI verifies via scripts/ci/verify_github_governance.py.",
+  "target": "dev",
+  "enforcement": "disabled",
+  "activation_requires": "M6 five-scenario draft-PR drill evidence with stable summaries (docs/governance/evidence/)",
+  "pull_request_required": true,
+  "approvals_required": 1,
+  "dismiss_stale_reviews": true,
+  "require_code_owner_review": true,
+  "block_force_pushes": true,
+  "block_deletions": true,
+  "bypass_actors": [],
+  "required_checks": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "last_verified": "2026-08-23"
+}

.github/governance/rulesets/master.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "Expected Ruleset state for branch master (release line). approvals_required=2 is BLOCKED on decision gate D3: only one maintainer is confirmed today. Until D3 unblocks, this ruleset must stay disabled and master governance must not be claimed complete.",
+  "target": "master",
+  "enforcement": "disabled",
+  "pending_decision_gate": "D3",
+  "enforcement_target": "active-after-D3",
+  "pull_request_required": true,
+  "approvals_required": 2,
+  "dismiss_stale_reviews": true,
+  "require_code_owner_review": true,
+  "block_force_pushes": true,
+  "block_deletions": true,
+  "bypass_actors": [],
+  "bypass_note": "Emergency bypass restricted to D4-confirmed release actors; every bypass needs an issue with reason, timestamp, and follow-up PR.",
+  "required_checks": [
+    "PR Governance / Summary",
+    "Tests / Quality Gate"
+  ],
+  "last_verified": "2026-08-23"
+}

.github/governance/rulesets/release-tags.json

@@ -0,0 +1,12 @@
+{
+  "$comment": "Tag ruleset for release tags (v*). Only D4-confirmed release actors may create/update/delete release tags. D4 is currently blocked (no pypi/testpypi environments, trusted publisher unconfirmed), so this ruleset stays disabled until M6 admin application.",
+  "target": "refs/tags/v*",
+  "enforcement": "disabled",
+  "pending_decision_gate": "D4",
+  "block_deletions": true,
+  "block_updates": true,
+  "block_creations_except_actors": true,
+  "bypass_actors": [],
+  "bypass_note": "Populate with D4-confirmed release actor IDs before enabling.",
+  "last_verified": "2026-08-23"
+}

.github/pull_request_template.md

@@ -0,0 +1,40 @@
+<!--
+  提交前请确认：普通贡献目标分支为 dev；master 仅接受 promotion 与 hotfix。
+  完整路由表见 docs/governance/branch-model.md
+-->
+## 目标分支与理由
+
+<!-- 必填。dev（默认）/ master（仅 promotion 或 hotfix/*）/ code-optimization（性能优化） -->
+
+## 变更类型与风险级别
+
+<!-- 必填。类型：feature / fix / docs / test / refactor / perf / chore
+     风险（按 docs/governance/branch-model.md §4）：
+     [ ] risk:r0 文档/测试
+     [ ] risk:r1 常规模块
+     [ ] risk:r2 核心/兼容性（BtApi、containers/feeds 基类、gateway、websocket、forwarding、CTP 接口）
+     [ ] risk:r3 发布/安全/供应链 -->
+
+## 兼容性 / 交易所影响
+
+<!-- 必填。涉及哪些交易所标识（如 BINANCE___SPOT）、Python 版本影响（3.11–3.13 阻塞矩阵；3.14 canary）、平台影响、公共 API 是否变化 -->
+
+## 已执行的测试与结果
+
+<!-- 必填。粘贴实际执行的命令与结果摘要，例如：
+     make test-fast
+     pytest tests/test_xxx.py -q
+     mkdocs build --strict   （文档变更时） -->
+
+## 子模块 SHA（如适用）
+
+<!-- 若本 PR 变更 gitlink 或 .gitmodules：旧 SHA → 新 SHA，插件仓 PR 链接，回滚 SHA。
+     协议详见 docs/governance/submodule-bump.md。不涉及则写 N/A -->
+
+## 安全 / 发布影响
+
+<!-- 是否触及凭据处理、订单路由、forwarding 网关、打包或发布路径？是→请说明并考虑加 risk:r3 标签 -->
+
+## 关联 Issue
+
+<!-- 关闭 XXX 时写 "Closes #XXX"；无关联 issue 请说明原因 -->