docs: streamline roadmap and PR governance

.github/ISSUE_TEMPLATE/work_item.yml

@@ -4,6 +4,18 @@ title: "Work: "
 labels:
   - enhancement
 body:
+  - type: dropdown
+    id: scope_level
+    attributes:
+      label: Scope level
+      description: Choose roadmap for an integrated outcome delivered through multiple child PRs; choose implementation for one cohesive review unit.
+      options:
+        - implementation
+        - roadmap
+        - research
+    validations:
+      required: true
+
   - type: dropdown
     id: work_type
     attributes:
@@ -50,7 +62,7 @@ body:
     id: deliverable
     attributes:
       label: Deliverable
-      description: What concrete output is expected?
+      description: What cohesive, reviewable output is expected? Include the code, config, tests, and docs needed to make that result complete.
       placeholder: |
         Examples:
         - merged code
@@ -60,13 +72,34 @@ body:
     validations:
       required: true
 
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope and delivery boundaries
+      description: Describe the work kept together for this outcome and the independently valuable work tracked elsewhere.
+      placeholder: |
+        In this work item:
+        - ...
+
+        Related follow-up or separate outcomes:
+        - ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: roadmap
+    attributes:
+      label: Roadmap relationship and target branch
+      description: For a roadmap, record its declared base branch, child issues, and planned dev/issue-<number>-<slug> integration branch. For a child issue, link the parent roadmap and use its integration branch as the PR base.
+
   - type: textarea
     id: done
     attributes:
       label: Definition of done
       description: List the acceptance criteria.
       placeholder: |
-        - CI green
+        - make test-all passes on the final local head
+        - current-head remote CI passes when the PR base is main
         - benchmark attached
         - docs updated
     validations:

.github/pull_request_template.md

@@ -7,12 +7,14 @@
 ## Linked Work
 
 - Issue:
+- Parent roadmap (when applicable):
+- Roadmap declared base (when applicable):
 - Milestone:
+- Base branch:
 
 ## Validation
 
-- [ ] `make check`
-- [ ] `uv run pytest -m "not slow"`
+- [ ] `make test-all` passed on the final local head before this PR was created or updated
 - [ ] Additional task-specific validation listed below
 
 Commands actually run:
@@ -21,6 +23,11 @@ Commands actually run:
 # paste exact commands here
 ```
 
+Remote CI route:
+
+- Base `main`: record the current-head CI link and status here.
+- Any other base: write `not scheduled; local make test-all is the test gate`.
+
 ## Impact
 
 - Backend impact: `mujoco` / `motrix` / both / none

AGENTS.md

@@ -14,13 +14,14 @@ UniLab 是一个 **高性能、模块化、contract 驱动** 的 RL infrastructu
 6. **Validate near risk**: 在最接近风险的边界补验证，不只跑顶层命令。
 7. **Cold-path asset access only**: asset/XML/model metadata 只允许在 init / materialization / cache 等低频路径处理；热路径不能解析 asset，也不能靠 `getattr` / `hasattr` 探测 backend 私有能力。
 
-## Roadmap 与 Issue Scope
+## Roadmap、Issue 与分支工作流
 
-- Roadmap 先用普通中文说明：只做什么、不做什么、预计规模和永久维护成本；maintainer 看不懂时必须停止并重写。
-- 一个 implementation issue 只允许一个主要结果，默认不超过 15 个文件、800 行净手写改动和一个 PR；超过即作为 umbrella 拆分，不能整单执行。
-- 批准 roadmap、umbrella 或“新建 issue”只授权规划；“开始开发”默认只授权当前明确确认的第一个 child issue。
-- 新公共 contract、execution path、runner/lifecycle、常规 CI、support 升级或 adapter production 化都必须单独确认，不得顺手扩张。
-- AI review、测试和 gate 不能代替产品判断，也不能证明 maintainer 已理解。
+- Roadmap 先用普通中文说明目标、交付边界、预计规模和永久维护成本，让 maintainer 能够据此作出产品与架构判断。
+- Implementation issue 围绕一个可审查的主要结果组织，并把实现该结果所需的代码、配置、测试和文档作为完整纵向切片。文件数和 LOC 用于估算 review 工作量；是否拆分取决于子项能否独立交付、验证、审查或回退。
+- Roadmap 获得开发授权后，先记录 declared base branch，再从该 base 的最新 head 创建 `dev/issue-<roadmap-number>-<slug>` 集成分支；declared base 可以是 `main`，也可以是上层 roadmap 的集成分支。每个 child issue 从本 roadmap 集成分支创建符合仓库类型惯例的分支并通过 PR 合回，最终由集成分支通过 PR 合回 declared base。
+- 已获批的 roadmap 范围支持连续推进 child issues。实施中新增公共 contract、execution path、runner/lifecycle、常规 CI、support 等级或 adapter production 化等长期责任时，先更新边界并请 maintainer 确认。
+- AI review、测试和 gate 为 maintainer 提供决策证据；产品方向与长期维护责任由 maintainer 确认。
+- 每个 PR 在创建或更新前于最终 head 运行 `make test-all`。base 为 `main` 的 PR 使用本地 gate、review 和远程 CI；其他 base 的 PR 使用本地 gate 与 review，远程资源集中用于实际进入 `main` 的合入边界。
 
 详细规则见[协作工作流](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md#ai-roadmap-与-issue-scope-治理)。
 
@@ -70,7 +71,7 @@ gh api repos/<owner>/<repo>/issues/<number> --jq '.body'
 
 ### PR 创建与管理
 ```bash
-gh pr create --title "标题" --body "内容" --base main
+gh pr create --title "标题" --body "内容" --base <target-branch>
 gh pr list
 gh pr view
 ```
@@ -80,10 +81,10 @@ gh pr view
 创建或更新 PR 前必须满足：
 
 1. 最终提交已经完成，且 `git status --short --branch` 确认工作树干净。
-2. 最终提交已经通过 `make test-all`。
-3. 如果用户明确说明已经跑过 `make test-all`，不要重复跑；但必须在 PR body 的 Validation 里记录 `make test-all` 已完成。
-4. 如果 `make test-all` 未通过且用户没有明确 override，不要创建或更新 PR。
-5. 创建或更新 PR 后，必须按当前 head SHA 等待远程 CI 全部结束并通过后才能报告完成；`pending` / `in_progress`、旧 head 的成功结果或挂起 job 都不算通过。失败或挂起时必须查看对应 job 日志并修复，除非用户明确 override。
+2. 最终提交已经通过本地 `make test-all`，并在 PR body 的 Validation 中记录结果。用户明确说明已在同一最终 head 运行该命令时，直接采用其结果。
+3. 本地 gate 通过后创建或更新 PR；maintainer 明确批准的 override 需记录在 PR body 中。
+4. PR base 为 `main` 时，按当前 head SHA 等待所有适用的远程 CI 结束并通过后再报告完成。`pending` / `in_progress`、旧 head 的结果和挂起 job 继续跟进；失败时查看对应 job 日志并处理，maintainer 明确批准的 override 除外。
+5. PR base 为集成分支或其他非 `main` 分支时，本地 `make test-all` 结果与 review 共同构成完整合入 gate；远程 CI 在后续实际 base 为 `main` 的 PR 上执行。
 
 ### CI 工作流查看
 ```bash
@@ -97,7 +98,7 @@ gh run list --status=failure
 ```bash
 gh api repos/unilabsim/UniLab/issues/174 --jq '.title, .body'
 git push -u origin fix/issue-174-ppo-config-alignment
-gh pr create --title "fix: xxx" --body "Fixes #174" --base main
+gh pr create --title "fix: xxx" --body "Fixes #174" --base <target-branch>
 ```
 
 ## Context

CONTRIBUTING.md

@@ -25,7 +25,7 @@ Languages: English | [简体中文](docs/sphinx/source/zh_CN/4-developer_guide/4
 ## Read Before You Start
 
 - Before changing training entrypoints, runners, env contracts, or backend paths, read [RL Infrastructure Development Standard](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md)
-- Before changing collaboration flow or issue / milestone rules, read [Collaboration Workflow](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md)
+- Before changing collaboration flow or issue / milestone rules, read [Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md)
 
 ## Common Commands
 
@@ -37,7 +37,7 @@ make check          # format + type (required before code-related commits)
 make test           # non-slow tests
 make test-cov       # non-slow tests + coverage report
 make test-slow      # slow integration and training smoke tests
-make test-all       # make check && make test-cov
+make test-all       # make check + make test-cov + benchmark entrypoint smoke
 ```
 
 ## Commit Conventions
@@ -54,14 +54,27 @@ Use Conventional Commits:
 
 ## Pull Request Workflow
 
-1. For code or config changes, run `make check` locally so lint, mypy, and pyright pass.
-2. For code changes, run `make test` locally so non-slow tests pass.
-3. If you touched IPC, Runner, or Config, add or update the matching tests.
-4. For docs-only changes, run `uv run pytest tests/scripts/test_check_docs.py -q` at minimum.
-5. If you touched repository hygiene rules, run `uv run pytest tests/scripts/test_repo_hygiene.py -q`.
-6. Link the relevant GitHub issue and fill in validation plus impact scope in the PR template.
-7. Open the PR against `main` and wait for green CI.
-8. Wait for code review.
+1. Choose and record the PR base before development. A roadmap child branches from its current integration branch; other work branches from its intended target branch.
+2. Run the tests nearest the changed contract. IPC, Runner, Config, docs, and repository-hygiene changes include their matching focused tests.
+3. Run `make test-all` on the final local head before creating or updating every PR, then record the command and result in the PR template.
+4. Link the driving issue and describe validation plus impact scope in the PR template.
+5. Open the PR against its intended base and complete code review.
+6. A PR whose base is `main` completes the applicable remote CI for its current head. A PR to another base uses the recorded local `make test-all` result as its complete test gate; remote execution occurs when an integrated result later reaches a `main`-base PR.
+
+## Roadmap Integration Workflow
+
+Once a roadmap issue is approved for development, record its declared base
+branch and create `dev/issue-<roadmap-number>-<slug>` from that base's latest
+head. The declared base may be `main` or another roadmap's integration branch.
+Create each child-issue branch from the latest integration branch using the
+repository's conventional type prefix, such as
+`feat/issue-<number>-<slug>` or `fix/issue-<number>-<slug>`, and set the child
+PR base to the integration branch. After the approved child issues are
+integrated, open the roadmap's final PR back to its declared base. Remote CI is
+required when that actual PR base is `main`.
+
+The detailed scope, authorization, and branch-update rules live in
+[Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md).
 
 ## Issue Reports
 
@@ -70,6 +83,6 @@ Use GitHub Issues to report bugs or propose features.
 ## Deep References
 
 - **Architecture & contracts**: [RL Infrastructure Development Standard](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md)
-- **Collaboration & ADR governance**: [Collaboration Workflow](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md)
+- **Collaboration & ADR governance**: [Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md)
 - **Test layout & markers**: [Development Standard §Testing](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md)
 - **Configuration system**: [Development Standard §Configuration](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md)

docs/sphinx/source/en/4-developer_guide/1-architecture/1-overview.md

@@ -63,8 +63,8 @@ validation at the boundary a change actually touched.
 | Backend path | the matching backend smoke run, plus a slow test when needed |
 | Training entrypoint | the relevant tests plus a 1-iteration smoke run |
 
-Use `make test` for the fast path and `make test-all` (`make check` plus
-`make test-cov`) before opening a PR.
+Use `make test` for the fast path and `make test-all` (`make check`,
+`make test-cov`, and `make test-benchmark-smoke`) before opening a PR.
 
 ## Review Checklist
 

docs/sphinx/source/en/4-developer_guide/4-contributing.md

@@ -71,17 +71,19 @@ make test-slow
 make test-all
 ```
 
-For docs-only changes, run:
+For documentation changes, run these focused checks in addition to
+`make test-all`:
 
 ```bash
 uv run pytest tests/scripts/test_check_docs.py -q
 cd docs/sphinx
 UNILAB_DOCS_SKIP_AUTODOC=1 uv run --no-project --with-requirements requirements.txt sphinx-build -b html -n source build/html
 ```
 
-The `Docs` GitHub Actions workflow runs the same prose-only build on matching
-PRs and pushes, and it can also be started from the GitHub Actions web UI via
-`workflow_dispatch`. It does not install UniLab with `pip install -e .`, does
+The `Docs` GitHub Actions workflow runs the same prose-only build for matching
+PRs whose base is `main` and for pushes to `main`. It can also be started from
+the GitHub Actions web UI via `workflow_dispatch`. It does not install UniLab
+with `pip install -e .`, does
 not generate API reference pages, and does not publish the external docs
 repository.
 
@@ -100,8 +102,13 @@ uv run --no-sync sphinx-build -j auto -b html -n source build/html
 
 - Use Conventional Commits such as `feat:`, `fix:`, `docs:`, `refactor:`,
   `test:`, and `chore:`.
+- Use `main` as the base for an ordinary PR. Use the roadmap's
+  `dev/issue-<roadmap-number>-<slug>` integration branch as the base for a child
+  PR. See {doc}`5-contributing_workflow` for the complete convention.
 - Link the driving issue in the PR.
 - List the validation commands actually run.
+- Pass `make test-all` on the final local head before creating or updating every
+  PR.
 - State whether behavior differs between MuJoCo, Motrix, macOS, or Linux.
 - For code/config changes, run the nearest tests for the changed contract before
   relying on top-level smoke commands.
@@ -154,18 +161,32 @@ Notes for `make test-slow`:
 
 ## CI Workflow
 
-Pull requests to `main` run five jobs in `.github/workflows/ci.yml`:
-`ruff-lint`, `ruff-format`, `mypy`, `pyright`, and `test`. Each is a required
-check, and the workflow can also be triggered manually via `workflow_dispatch`.
-In-progress runs on the same branch are cancelled automatically.
+Remote CI is routed by the PR base:
+
+| PR base | Local gate | Remote gate |
+| --- | --- | --- |
+| `main` | `make test-all` passes on the final local head | All applicable checks for the current PR head complete successfully |
+| Any other branch, including a roadmap integration branch | `make test-all` passes on the final local head | The local result is the complete test gate; a later PR whose actual base is `main` provides remote execution |
+
+A child PR can therefore merge into its integration branch after local
+validation and review. A roadmap's final PR returns to its declared base: a
+`main` base runs remote integration, while another base continues with the local
+gate. Record the actual local commands and results in every PR, and add the
+current-head remote status when the base is `main`.
+
+Pull requests to `main` run six jobs in `.github/workflows/ci.yml`:
+`ruff-lint`, `ruff-format`, `mypy`, `pyright`, `benchmark-smoke`, and `test`.
+They can also be triggered with `workflow_dispatch` for mainline-boundary
+diagnostics. In-progress runs on the same branch are cancelled automatically.
 
 | Job | What it runs |
 | --- | --- |
 | `ruff-lint` | `uv run --no-sync ruff check --output-format=github .` |
 | `ruff-format` | `uv run --no-sync ruff format --check .` |
 | `mypy` | `uv run mypy src/unilab` |
 | `pyright` | `uv run pyright` |
-| `test` | `uv sync --extra motrix` (CPU torch), then `uv run --no-sync pytest -m "not slow" --cov=unilab --cov-fail-under=25` |
+| `benchmark-smoke` | `uv run --no-sync python scripts/benchmark/smoke_test.py` in a CPU torch environment |
+| `test` | `uv sync --extra mujoco --extra motrix` (CPU torch), then `uv run --no-sync pytest -m "not slow" --cov=src/unilab --cov-fail-under=25` |
 
 The `test` job enforces a coverage gate (`--cov-fail-under=25`); the floor only
 ratchets up as test guardrails improve. Documentation changes are validated by