docs(governance): 收紧开发环境文档约定

同步模板治理约定在项目文档中的落点，明确宿主机只作为容器入口，不再引导安装项目开发依赖。

- 移除 README 和 docs/docker.md 中的 Dev Container CLI 全局安装提示。
- 将 README、AGENTS、CONTRIBUTING 和 docs/docker.md 的项目命令统一为 devcontainer exec 入口。
- 补齐 Copyright、注释、DCO、文件规模和运行时配置约定，并记录后续全仓库文件头检查。

验证：
- git diff --check
- git diff --staged --check
- rg 检查宿主机安装指令和裸项目命令示例无残留
- staged diff 新增行凭据扫描无匹配

Co-authored-by: OpenAI Codex <noreply@openai.com>
Signed-off-by: Niu Zhihong <zhihong@nzhnb.com>

Author: MRNIU

AGENTS.md

@@ -1,3 +1,5 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
 # AGENTS.md — SimpleKernel
 
 ## OVERVIEW
@@ -69,19 +71,27 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 
 ## CONVENTIONS
 
-> Full Rust coding conventions: `docs/design/00-概述.md` §9
+> Full project conventions: `docs/conventions.md`; legacy phase design conventions: `docs/design/00-概述.md` §9
 
 ### Environment
 - **容器优先**：凡是能在 Dev Container / Docker 中完成的构建、检查、`pre-commit`、固件构建、QEMU 运行和系统测试，都应在容器内执行，不要为本项目修改宿主机工具链。
-- **宿主机边界**：宿主机只负责 Docker 或兼容容器运行时、Dev Container CLI/扩展、Git 等入口工具；不要在宿主机安装 Rust nightly、交叉编译器、QEMU 或固件构建依赖来绕过容器。
+- **宿主机边界**：宿主机只负责 Docker 或兼容容器运行时、Git、编辑器/AI agent 和已有 Dev Container 入口工具；不要在宿主机安装 Rust nightly、交叉编译器、QEMU、固件构建依赖或其他项目开发依赖来绕过容器。
 - **命令入口**：在宿主机发起命令时优先使用 `devcontainer exec --workspace-folder . <command>`，或使用当前已构建的项目开发镜像运行等价命令。
-- **例外**：只有容器不可用、任务明确要求本地环境，或正在修复容器自身配置时，才考虑宿主机执行；说明原因并保持宿主/容器步骤边界清晰。
+- **例外**：只有正在修复容器自身配置、文档/Git 等入口操作，或任务明确要求无需项目工具链的本地操作时，才考虑宿主机执行；说明原因并保持宿主/容器步骤边界清晰。
 
 ### Git
 - **Commit 格式**: `<type>(<scope>): <subject>` — type: feat/fix/refactor/test/docs/chore
 - **Sign-off 必须**: 每条 commit 必须使用 `git commit --signoff`（DCO 签署），**不可省略**
+- **DCO 门禁**：PR CI 会检查每个 commit 是否包含 `Signed-off-by` trailer。
+- **Commit 模板**：可执行 `git config commit.template .gitmessage` 启用仓库提交模板；模板必须镜像 `docs/git.md`。
 - **Subagent 派发时**：给 subagent 的 commit 指令中也必须包含 `--signoff`
 
+### Repository Hygiene
+- **Copyright**：仓库自有源码、脚本、CI 配置、重要项目配置和长期维护文档，新增时应带 `Copyright The SimpleKernel Contributors` 文件头；严格 JSON 或不支持注释的文件不强行加入文件头。
+- **机器可读格式**：`.json` 文件保持严格 JSON，不写注释、不留尾随逗号；需要说明时写在相邻文档。
+- **文件规模**：手写源码超过 300 行时 review 应检查职责边界；原则上不超过 500 行，超过时 PR 需说明暂不拆分理由或拆分计划。
+- **运行时配置**：FDT、MMIO、timer 频率、core count、QEMU 参数、固件路径和硬件拓扑等运行时/platform 输入必须显式校验；缺失或非法输入应 fail fast，不用 `Default`、`unwrap_or(...)` 等隐式 fallback 掩盖。
+
 ### Rust
 - **Language**: Rust nightly, `#![no_std]`, `#![no_main]`, edition 2024
 - **Naming**: `snake_case` functions/methods, `PascalCase` types/traits/enums, `SCREAMING_SNAKE_CASE` constants
@@ -91,6 +101,7 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 - **Doc comments**: `///` with `# Safety`, `# Errors`, `# Panics` sections for public APIs（节标题保留英文，内容用中文）
 - **注释语言**: 所有注释和文档注释使用中文；`// SAFETY:` 前缀保留英文（Rust 社区惯例），其后说明用中文
 - **注释位置**: 注释写在代码上方，不写在行尾（`// SAFETY:` 除外——紧跟 `unsafe` 块上方）
+- **注释内容**: 注释解释原因、不变量和失败后果，不重复代码表面含义；临时 TODO 必须说明触发条件、后续处理位置或关联文档。
 - **Error handling**: Syscall boundary uses `Result<T, ErrorCode>` + `?`; kernel internals use `.expect("reason with data")` or `panic!()` — the kernel must not silently proceed on internal errors
 - **Unsafe**: Every `unsafe` block MUST have `// SAFETY:` comment explaining invariants; minimize scope
 - **Singletons**: `spin::Once<T>` with `call_once()` / `get()`
@@ -122,28 +133,31 @@ docs/design/         # Design docs (SAS architecture, subsystem designs, phase p
 - Cargo workspace: root package (kernel) + `xtask` (build tool)
 
 ## COMMANDS
+宿主机侧执行项目命令时使用 `devcontainer exec --workspace-folder . <command>`。
+
 ```bash
 # Build kernel
-cargo xtask build --arch riscv64
-cargo xtask build --arch aarch64
+devcontainer exec --workspace-folder . cargo xtask build --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask build --arch aarch64
 
 # Run in QEMU (via xtask — handles FIT image + TFTP + QEMU)
-cargo xtask run --arch riscv64
-cargo xtask run --arch aarch64
+devcontainer exec --workspace-folder . cargo xtask run --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask run --arch aarch64
 
 # Debug (GDB on localhost:1234)
-cargo xtask debug --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask debug --arch riscv64
 
 # System tests in QEMU
-cargo xtask test --arch riscv64                        # all standalone tests
-cargo xtask test --arch riscv64 --name panic-test      # specific standalone test
-cargo xtask test --list                                # list available tests
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name panic-test
+devcontainer exec --workspace-folder . cargo xtask test --list
 
 # Format + lint check
-cargo fmt --check && cargo clippy -- -D warnings
+devcontainer exec --workspace-folder . cargo fmt --check
+devcontainer exec --workspace-folder . cargo clippy -- -D warnings
 
 # Documentation
-cargo doc --no-deps
+devcontainer exec --workspace-folder . cargo doc --no-deps
 ```
 
 **QEMU 超时**：在 QEMU 中运行内核或测试时经常出现卡死或无限循环打印日志的情况。所有通过 Bash 工具执行的 QEMU 相关命令（`cargo xtask run`、`cargo xtask test`）**必须设置 30 秒超时**（`timeout: 30000`）。超时后应 `pkill -f qemu-system` 清理残留进程。
@@ -157,9 +171,9 @@ cargo doc --no-deps
 每个测试是独立的 `#![no_std]` 裸机二进制，启动独立 QEMU 实例，拥有干净的内核环境。
 
 ```bash
-cargo xtask test --arch riscv64                        # 全部独立测试
-cargo xtask test --arch riscv64 --name frame-alloc-test # 指定测试
-cargo xtask test --list                                # 列出可用测试
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name frame-alloc-test
+devcontainer exec --workspace-folder . cargo xtask test --list
 ```
 
 测试基础设施位于 `tests/test_harness/`，核心是 `test_main!` 宏：

CONTRIBUTING.md

@@ -1,23 +1,25 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
 # 贡献指南
 
 感谢参与 SimpleKernel。提交前请先阅读根目录 `AGENTS.md`、`docs/conventions.md` 和 `docs/git.md`。
 
 ## 开发环境
 
-开发环境默认使用 Dev Container。宿主机只需要 Docker 或兼容容器运行时、Dev Container CLI/扩展、Git 等入口工具；不要为了本项目在宿主机安装 Rust nightly、交叉编译器、QEMU 或固件构建依赖。
+开发环境默认使用 Dev Container。宿主机只保留 Docker 或兼容容器运行时、Git、编辑器/AI agent 和已有 Dev Container 入口工具；不要为了本项目在宿主机安装 Rust nightly、交叉编译器、QEMU、固件构建依赖或其他项目开发依赖。
 
 ```bash
 devcontainer up --workspace-folder .
 devcontainer exec --workspace-folder . bash
 ```
 
-容器内常用命令：
+宿主机侧常用命令：
 
 ```bash
-cargo xtask build --arch riscv64
-cargo xtask test --arch riscv64
-cargo fmt --check
-cargo clippy -- -D warnings
+devcontainer exec --workspace-folder . cargo xtask build --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
+devcontainer exec --workspace-folder . cargo fmt --check
+devcontainer exec --workspace-folder . cargo clippy -- -D warnings
 ```
 
 通过 Bash 工具运行 QEMU 相关命令时必须设置 30 秒超时；超时后清理残留 QEMU 进程。
@@ -37,6 +39,8 @@ cargo clippy -- -D warnings
 |------|--------------|
 | 启动流程、命令、测试入口变化 | `README.md`、`docs/README.md`、相关 SOP |
 | 架构不变量变化 | `docs/adr/`、SAD/SDD、`AGENTS.md` |
+| 项目长期约定、Copyright、注释、文件规模、运行时配置规则变化 | `AGENTS.md`、`docs/conventions.md` |
+| Git/commit/DCO/提交模板变化 | `docs/git.md`、`.gitmessage`、PR 模板 |
 | 公开 trait、错误码、类型或模块边界变化 | 代码文档注释、SDD、模块 README |
 | 固件、第三方源码、供应商交付物变化 | `3rd/` 记录、`docs/suppliers/`、`docs/production/` |
 | 硬件或生产流程变化 | `docs/hardware/`、`docs/sop/` |
@@ -48,6 +52,9 @@ cargo clippy -- -D warnings
 - 不使用 `.unwrap()`；错误信息必须包含有助于定位问题的数据。
 - 内核互斥使用项目自定义 `SpinLock<T>`。
 - trait 是契约，不要为了某个实现把实现细节塞进 trait 定义。
+- 新增自有源码、脚本、CI 配置、重要配置和长期维护文档时按 `docs/conventions.md` 添加 Copyright 文件头。
+- 手写源码超过 300 行时主动检查职责边界；超过 500 行时 PR 说明暂不拆分理由或拆分计划。
+- 运行时/platform 输入缺失或非法时 fail fast，不用隐式默认值掩盖配置或硬件描述问题。
 
 ## Commit
 
@@ -56,3 +63,11 @@ commit 使用 `docs/git.md` 中的格式，并且必须带 DCO sign-off：
 ```bash
 git commit --signoff -m "docs(conventions): 补充文档结构约定"
 ```
+
+可选启用仓库提交模板：
+
+```bash
+git config commit.template .gitmessage
+```
+
+PR CI 会检查每个 commit 是否包含 `Signed-off-by` trailer。

README.md

@@ -1,3 +1,5 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
 [![codecov](https://codecov.io/gh/Simple-XX/SimpleKernel/graph/badge.svg?token=J7NKK3SBNJ)](https://codecov.io/gh/Simple-XX/SimpleKernel)
 ![workflow](https://github.com/Simple-XX/SimpleKernel/actions/workflows/workflow.yml/badge.svg)
 ![commit-activity](https://img.shields.io/github/commit-activity/t/Simple-XX/SimpleKernel)
@@ -86,11 +88,11 @@ pub trait Scheduler: Send + Sync {
 #### 3. 测试验证
 
 ```bash
-# 单元测试（宿主机）
-cargo test
+# 单元测试
+devcontainer exec --workspace-folder . cargo test
 
 # 系统测试（QEMU）
-cargo xtask test --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
 ```
 
 #### 4. 对照参考实现
@@ -124,8 +126,7 @@ cd SimpleKernel
 # 安装 Dev Containers 扩展后，点击左下角 >< 图标
 # 选择 "Reopen in Container"
 
-# 或使用 CLI
-npm install -g @devcontainers/cli
+# 或使用已存在的 Dev Container CLI
 devcontainer up --workspace-folder .
 devcontainer exec --workspace-folder . bash
 ```
@@ -134,35 +135,35 @@ devcontainer exec --workspace-folder . bash
 >
 > 详细说明见 [Dev Container 文档](./docs/docker.md)
 
-> 开发环境默认优先使用 Dev Container。除安装 Docker、Dev Container CLI/扩展、
-> Git 等入口工具外，不需要在宿主机安装 Rust nightly、交叉编译器、QEMU 或固件构建依赖。
+> 开发环境默认优先使用 Dev Container。宿主机只保留 Docker 或兼容容器运行时、
+> Git、编辑器/AI agent 和已有 Dev Container 入口工具；不要为了本项目在宿主机安装开发依赖。
 
 **方式二：修复容器或执行明确要求的本地任务**
 
-默认不在宿主机安装 Rust nightly、交叉编译器、QEMU 或固件构建依赖。只有容器不可用、正在修复容器自身配置，或任务明确要求本地环境时，才在宿主机执行，并在 PR 中说明原因和验证边界。
+默认不在宿主机安装 Rust nightly、交叉编译器、QEMU、固件构建依赖或其他项目开发依赖。只有正在修复容器自身配置、文档/Git 等入口操作，或任务明确要求无需项目工具链的本地操作时，才在宿主机执行，并在 PR 中说明原因和验证边界。
 
 ### 编译与运行
 
-```bash
-cd SimpleKernel
+以下项目命令通过 Dev Container、Codespaces 或 CI 声明的隔离环境执行；宿主机只作为 Docker/Dev Container 编排入口。
 
+```bash
 # 编译内核
-cargo xtask build --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask build --arch riscv64
 
 # 在 QEMU 模拟器中运行
-cargo xtask run --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask run --arch riscv64
 
 # 调试（GDB 连接 localhost:1234）
-cargo xtask debug --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask debug --arch riscv64
 
-# 单元测试（宿主机 x86_64）
-cargo test
+# 单元测试
+devcontainer exec --workspace-folder . cargo test
 
 # 系统测试（QEMU 中运行）
-cargo xtask test --arch riscv64           # 统一测试内核
-cargo xtask test --arch riscv64 --all     # 全部测试（统一 + 独立）
-cargo xtask test --arch riscv64 --name panic-test  # 指定独立测试
-cargo xtask test --list                   # 列出可用测试
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --all
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name panic-test
+devcontainer exec --workspace-folder . cargo xtask test --list
 ```
 
 **支持的架构：**
@@ -218,12 +219,12 @@ SimpleKernel/
 
 SimpleKernel 采用两层测试 + 冒烟测试：
 
-### 单元测试（宿主机）
+### 单元测试（容器内 host target）
 
-纯逻辑 crate 的 `#[test]` 模块，在宿主机上运行：
+纯逻辑 crate 的 `#[test]` 模块，在容器内以宿主架构运行：
 
 ```bash
-cargo test -p memory_types -p config -p page_table_entry -p arch
+devcontainer exec --workspace-folder . cargo test -p memory_types -p config -p page_table_entry -p arch
 ```
 
 覆盖范围：地址运算、PTE 编解码、常量验证等。
@@ -233,9 +234,9 @@ cargo test -p memory_types -p config -p page_table_entry -p arch
 每个测试是独立的 `#![no_std]` 裸机二进制，启动独立 QEMU 实例，拥有干净的内核环境。
 
 ```bash
-cargo xtask test --arch riscv64 --all          # 全部测试
-cargo xtask test --arch riscv64 --name <name>  # 指定测试
-cargo xtask test --list                        # 列出可用测试
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --all
+devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --name <name>
+devcontainer exec --workspace-folder . cargo xtask test --list
 ```
 
 测试位于 `tests/` 目录，使用 `tests/test_harness/` 提供的 `test_main!` 宏消除样板代码。
@@ -295,6 +296,7 @@ cargo xtask test --list                        # 列出可用测试
 - **格式化**: `rustfmt.toml`（100 字符宽度），`cargo fmt` 强制执行
 - **静态检查**: `cargo clippy -- -D warnings`
 - **注释语言**: 所有注释和文档注释使用中文；`// SAFETY:` 前缀保留英文
+- **完整约定**: Copyright、注释、文件规模、严格 JSON、第三方代码和运行时配置规则见 [docs/conventions.md](./docs/conventions.md)
 
 ### 命名约定
 
@@ -310,11 +312,17 @@ cargo xtask test --list                        # 列出可用测试
 ```
 <type>(<scope>): <subject>
 
-type: feat|fix|docs|style|refactor|perf|test|build|revert
+type: feat|fix|refactor|test|docs|chore|build|ci|perf|style|revert
 scope: 可选，影响的模块 (arch, memory, task, xtask)
 ```
 
 每条 commit 必须使用 `git commit --signoff`（DCO 签署）。
+PR CI 会检查每个 commit 是否包含 `Signed-off-by` trailer。
+可选提交模板：
+
+```bash
+git config commit.template .gitmessage
+```
 
 ## 文档入口
 
@@ -346,8 +354,8 @@ scope: 可选，影响的模块 (arch, memory, task, xtask)
 
 1. Fork 本仓库
 2. 创建功能分支: `git checkout -b feat/amazing-feature`
-3. 遵循代码规范进行开发
-4. 确保所有测试通过: `cargo test && cargo xtask test --arch riscv64 --all`
+3. 遵循 `AGENTS.md`、`docs/conventions.md` 和 `docs/git.md` 进行开发
+4. 确保相关测试通过，例如 `devcontainer exec --workspace-folder . cargo test` 和 `devcontainer exec --workspace-folder . cargo xtask test --arch riscv64 --all`
 5. 提交变更: `git commit --signoff -m 'feat(scope): add amazing feature'`
 6. 创建 Pull Request
 

docs/README.md

@@ -1,3 +1,5 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
 # docs/
 
 本目录保存 SimpleKernel 的项目文档。代码是实现真值源；当历史设计文档与代码冲突时，以当前代码为准，并在审查记录或 ADR 中标出差异。
@@ -36,8 +38,8 @@ docs/
 | 跟踪审计阶段目标、进度和发现 | `docs/audit/` |
 | 记录硬件接口、固件、生产、供应商或 SOP | `docs/hardware/`、`docs/production/`、`docs/suppliers/`、`docs/sop/` |
 | 创建局部协作规则或新文档 | `docs/templates/` |
-| 记录长期工程约定 | `docs/conventions.md` |
-| 记录 Git 和 commit 规范 | `docs/git.md` |
+| 记录长期工程约定，包括 Copyright、注释、文件规模、严格 JSON、第三方代码和运行时配置 | `docs/conventions.md` |
+| 记录 Git、commit、DCO 和 `.gitmessage` 规范 | `docs/git.md` |
 
 ## SAD、SDD 与历史文档边界
 

docs/conventions.md

@@ -1,3 +1,5 @@
+<!-- Copyright The SimpleKernel Contributors -->
+
 # 项目约定
 
 本文记录 SimpleKernel 长期协作约定。审计阶段的临时规则仍以根目录 `AGENTS.md` 的“CURRENT PHASE”部分为准；临时规则清理后，应把仍然有效的规则沉淀到本文。
@@ -17,6 +19,7 @@
 - 严格 JSON 文件不写注释，也不为了版权头破坏 JSON 兼容性；需要说明版权、用途或格式约束时，写在相邻 README 或文档中。
 - 第三方代码、vendor copy、submodule、许可证正文和生成文件保留其上游或生成器声明，不改写为 SimpleKernel 版权头。
 - 既有文件没有版权头时，不为补版权做大规模无关 churn；在本次修改触及且格式允许时顺手补齐即可。
+- 后续需要做一次全仓库 Copyright 与文件头检查，统一确认哪些文件需要补头、哪些文件因格式或来源应豁免。
 
 ## 注释写法