docs(gitops): add local development workflow convention

Document the split between the local efficient development layer
(clone/fetch/agent branch/modify/verify/commit/push non-main) and the
remote governance control plane (protected main, PR + Owner approval,
CAS/generation, release approval).  Emphasizes grouped commits, forbids
git reset --hard, and keeps governance read-only pending formal
scoped-writer authorization.  A code/documentation change only; does not
request GitOps write access.

docs/gitops/local-development-workflow-cn.md

@@ -0,0 +1,102 @@
+# AIOS 本地开发工作流约定（CN）
+
+> 适用范围：具备本地工作区能力的执行环境（人 / Agent）。
+> 定位：本地高效开发层（clone / fetch / 分支 / 修改 / 验证 / commit / push 到非 main 分支）。
+> **不绕过**远端现有治理：branch protection、CAS、generation、release approval 等保持不变。
+> 本文档为流程约定，不是治理授权；不开放任何 GitOps 写权限。
+
+---
+
+## 1. 分层原则
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  开发层（本地 git worktree）                                    │
+│    clone/reuse → 拉最新基线 → agent/* 分支 → 修改 → 本地验证    │
+│    → commit → push 远端 非 main 分支                           │
+├───────────────────────────────────────────────────────────────┤
+│  治理控制面（Gitea + gitops 治理）                              │
+│    protected main（禁 direct push / force / tag / baseline）   │
+│    PR + Owner approval → CAS/generation 校验 → release 流程     │
+│    scoped writer 授权 / Admission / GitOps gate                │
+└───────────────────────────────────────────────────────────────┘
+```
+
+本地 Git 是高效开发层，不应绕过治理控制面。仅当本地环境不可用、需要读取生产运行事实、或必须通过 AIOS 治理 API 执行的动作，才直接走远端控制面。
+
+---
+
+## 2. 远端与开发基线
+
+- 远端：`https://g.cnnetmkt.top/git/aios/aios.git`（Gitea，仅 HTTPS）
+- 默认分支：`main`（protected）
+- 开发分支前缀：`agent/*`（开发）、`acceptance/*`（验收）、`patch/*`（平台修复）
+- 本地 git 身份：由 operator 配置（本仓库内配置，不写全局，避免污染其他仓库）
+
+---
+
+## 3. 每次开发的固定动作
+
+### 3.1 拉取最新基线
+
+```bash
+git status --short            # 必须确认无未提交修改，再动基线
+git fetch origin
+git checkout main
+git pull --ff-only origin main
+```
+
+> **禁止 `git reset --hard`。**
+> `reset --hard` 存在误覆盖 Owner 工作与 Agent 中间产物的风险；AIOS 保护 Owner 工作与 Agent 产物。
+> 基线漂移（本地与 `origin/main` 分叉、或授权 base OID 漂移）通过**检查 + 重新绑定**解决，而非覆盖丢弃。
+> 涉及授权基准漂移（AUTHORIZED_BASE_OID_DRIFT）时必须由 Owner 重新授权，不得静默 rebase。
+
+### 3.2 创建开发分支
+
+```bash
+git checkout -b agent/<描述> origin/main
+# 示例：agent/fix-auth-timeout-20260908、agent/repository-discovery-p0-20260902
+```
+
+### 3.3 修改 + 成组提交
+
+- **成组**：一组逻辑完整的内容 → 一个 commit。不要"每改一个文件就 commit/push"。
+- 提交信息遵循仓库风格：`feat(...)` / `fix(...)` / `chore(...)`（参考 `git log`）。
+- **禁止**提交：密钥、token、签名材料、明文凭据（仓库配有 `.gitleaks.toml`）。
+
+### 3.4 本地验证
+
+- 按 `AGENT_DEPLOYMENT_REQUIREMENTS.md` 及各 scope 测试要求在本地运行验证
+  （`python3 -m unittest`、smoke、`py_compile` 等），通过后再 commit + push。
+
+### 3.5 同步远端
+
+```bash
+git push -u origin agent/<分支>
+```
+
+推送非 main 分支后，交由远端治理决定是否合入 main。
+
+---
+
+## 4. 治理边界（严格遵守）
+
+以下操作必须留在远端治理控制面，本地 git 一律不做：
+
+- `main` 直接 push / merge —— 走 protected PR + Owner approval
+- `force push` / 历史重写 —— 全程禁止
+- tag 创建 / 更新 / 删除 —— 属 release approval，Owner 控制
+- baseline（生产基线）写入 —— Owner 控制
+- 分支删除 —— Owner 控制
+- 仓库管理 / 管理员操作 —— Owner 控制
+- 生产 / 发布部署标记 —— 走验收 + release approval
+
+---
+
+## 5. 状态登记与授权
+
+- 当前 `AIOS_GITOPS_WRITES_ENABLED=false` 为**预期状态**：Agent 不可直接写 GitOps 状态，符合
+  "禁止绕过 Admission / GitOps gate" 的治理设计。
+- 本文档建议通过普通代码变更（agent 分支 + PR）提交收录，**不要求、也不应打开 GitOps 写权限**。
+- 待 `AIOS_GITOPS_WRITES_ENABLED` 或正式 scoped writer 授权开启后，如需将该约定登记到 AIOS
+  控制面，再由 Owner / 治理 API 执行。