Document stock repos adoption matrix and new project admission spec
Why: Provide phased rollout roadmap (Phases 1-5) for stock repositories and mandatory defaults for new projects under governance v2. Evidence: Specification documented in docs/superpowers/specs/2026-10-16-stock-repos-adoption-matrix.md. Impact: Clarifies U6 and U7 governance deliverables for multi-repo rollout without ambiguity. Refs: feature/development-governance-v2
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
# 存量仓采纳矩阵与新项目默认准入规范（U6 & U7）
|
||||
|
||||
## 一、背景与定位
|
||||
|
||||
在 `Development-Guidelines`（v0.1.0-draft.10）确立通用工程 Agent 契约（硬边界 8、agent-per-unit、会话隔离、JSON 终态收据、无 host 隐式代写、受控 transport/admission）以及两级分支模型（`initiative` → `child` → `main`）后，各仓库需要统一演进路径，避免规则漂移与层级倒置。
|
||||
|
||||
本规范制定存量仓库分批采纳矩阵（U6）与新项目默认准入标准（U7）。
|
||||
|
||||
---
|
||||
|
||||
## 二、存量仓库采纳矩阵（U6）
|
||||
|
||||
### 1. 仓库清单与角色定位
|
||||
|
||||
| 仓库名称 | 路径/标识 | 当前类型 | 治理批次 | 重点要求 |
|
||||
|---|---|---|---|---|
|
||||
| **Development-Guidelines** | `deps/development-guidelines` | 规范权威仓 | **Phase 1**（当前） | 核心硬边界 8、`standards/agent-execution.md`、模板与 JSON Schema（PR #7） |
|
||||
| **Agent-System-Dev** | `.`（编排根仓） | 顶层试点仓 | **Phase 1**（当前） | 两级分支与 triage 门禁、`AGENT-EXECUTION.md` 引用上游标准、本地 `agent_exec.py` 严格校验 |
|
||||
| **Development-Manager** | `Development-Manager` | 平台工具/服务 | **Phase 2** | `runner.go` 协议对齐 Draft.10 Schema、提供共享执行与 transport/admission 能力 |
|
||||
| **Agent-System-Core** | `modules/core` | 核心引擎 | **Phase 3** | 配置 `AGENT-EXECUTION.md`、接入 pre-commit admit 校验、支持 initiative 子任务交付 |
|
||||
| **Agent-System-Backend** | `modules/backend` | 业务后端 | **Phase 3** | 配置 `AGENT-EXECUTION.md`、子模块对齐、API 变更必须经隔离执行单元 |
|
||||
| **Agent-System-Frontend** | `modules/frontend` | 业务前端 | **Phase 4** | UI 设计门禁（Tokens/Motion）+ Agent 执行门禁，双重校验 |
|
||||
| **Agent-System-UI** | `modules/ui` | 组件库 | **Phase 4** | 独立 tokens 变更、组件重构必须保持单元隔离与独立 Review |
|
||||
| **Agent-System-Documents** | `modules/documents` | 文档服务 | **Phase 4** | Python 环境与轻量脚本走受控执行 |
|
||||
| **Agent-System-RDM** | 独立 RDM 仓 | 数据研发管理 | **Phase 4** | 数据模型与工作台变更走两级分支 |
|
||||
| **Shared Libraries** (`agent-command`, `agent-native`, `agent-squad`, `agent-intent`, `error-code-system`, `logging-system`) | `deps/*` | 基础叶子库 | **Phase 5** | 极简 `AGENT-EXECUTION.md` 配置，杜绝跨仓随意手工修改 |
|
||||
|
||||
### 2. 分批推进策略与准出条件
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
P1["Phase 1: Guidelines 规范升级 & Dev 试点<br>(PR #7 + Dev 两级分支 & triage)"] --> P2["Phase 2: Development-Manager 共享执行器对齐<br>(Runner Schema & Transport 统一)"]
|
||||
P2 --> P3["Phase 3: Core & Backend 核心系统采纳<br>(两级分支 + AGENT-EXECUTION.md + admit)"]
|
||||
P3 --> P4["Phase 4: Frontend, UI & 周边服务采纳<br>(设计门禁 + 执行门禁联动)"]
|
||||
P4 --> P5["Phase 5: 共享叶子库全面接入<br>(无免死金牌，全代码库强制受控实施)"]
|
||||
```
|
||||
|
||||
#### Phase 1（本大任务范围）：规范权威冻结与编排仓试点
|
||||
- **目标**：上游 Guidelines 确立合同与 Schema，Dev 仓实现两级生命周期与 triage，并作为试点验证完整 agent-per-unit 交付流程。
|
||||
- **准出**：Guidelines PR #7 进入 review/待合并状态；Dev 仓 `test_task.py` 全部通过，`task-triage` 正常分流，`policy/delivery.md` 与 `AGENTS.md` 对齐。
|
||||
|
||||
#### Phase 2：共享执行器与平台工具对齐
|
||||
- **目标**：Development-Manager 基于 [docs/superpowers/specs/2026-10-16-shared-executor-audit.md](2026-10-16-shared-executor-audit.md) 收敛 runner 实现，支持机器可读收据、HMAC 完整性签名及快进应用。
|
||||
- **准出**：DM CLI 可直接作为通用底层，替代零散拷贝。
|
||||
|
||||
#### Phase 3：核心后端系统（Core / Backend）采纳
|
||||
- **目标**：业务最密集、风险最高的两个系统接入：
|
||||
1. 根目录建立 `AGENT-EXECUTION.md`。
|
||||
2. 启用本地 pre-commit 钩子（集成分支防直推 + `admit` 校验）。
|
||||
3. 大任务（如数据流重构、跨模块协议升级）强制切 `feature/<initiative>`，日常小卡片切 `feature/<initiative>-<child>` 或 standalone。
|
||||
|
||||
#### Phase 4：前端、UI 与周边服务采纳
|
||||
- **目标**：与现行 `DESIGN.md` 设计门禁深度绑定，UI 令牌与组件重构使用隔离单元执行与独立 Review。
|
||||
|
||||
#### Phase 5：全量叶子库采纳
|
||||
- **目标**：消灭任何“因为是小库就可以由主智能体直接手工写”的特权空间。所有库统一受控。
|
||||
|
||||
---
|
||||
|
||||
## 三、每个仓库采纳的标准动作清单
|
||||
|
||||
每个存量仓库在纳入治理时，必须完成以下 5 步：
|
||||
|
||||
1. **引入项目配置**：
|
||||
从 `templates/AGENT-EXECUTION.md.template` 复制到仓库根目录 `AGENT-EXECUTION.md`，根据仓库需求配置角色候选顺序（默认：implementation/repair 为 cursor/antigravity/pi，test/review 为 pi/antigravity/cursor/codex）。
|
||||
2. **挂接本地门禁**：
|
||||
在 `scripts/hooks/pre-commit` 中接入集成分支防直提检查与 `agent_exec.py admit`（或平台提供的 admit 检查）。
|
||||
3. **引入两级分支管理**：
|
||||
在任务管理脚本中支持 `branch_kind`（initiative / child / standalone）、`task-triage` 检查与 `immediate_target` 同步。
|
||||
4. **任务卡模板升级**：
|
||||
采纳带两级分支元数据与 Agent 实施收据表格的统一模板（`templates/task-card.md`）。
|
||||
5. **在 `policy/facts.md` 与 `adoption.md` 中登记**：
|
||||
记录采纳版本、已验证的 CLI 候选及最后审计时间戳。
|
||||
|
||||
---
|
||||
|
||||
## 四、新项目默认准入规范（U7）
|
||||
|
||||
对于任何新建仓库（包含微服务、工具库、实验项目）：
|
||||
|
||||
1. **非可选硬门禁**：
|
||||
- 根据 `workflows/adoption.md`，`AGENT-EXECUTION.md` 与项目任务管理门禁为**必需项（MANDATORY）**。
|
||||
- “本项目没有产品业务 Agent”**不得作为豁免工程 Agent 执行规则的理由**。
|
||||
2. **脚手架默认预置**：
|
||||
- 仓库初始化模版必须内置：
|
||||
- `AGENT-EXECUTION.md`（配置 Draft.10 Schema 标准）
|
||||
- `policy/delivery.md`（明确 goal-first 与两级分支交付）
|
||||
- `scripts/hooks/pre-commit`（接线执行门禁）
|
||||
3. **CI 流水线验证**：
|
||||
- CI 流水线必须包含 `agent-execution.schema.json` 语法校验，防止配置损坏。
|
||||
4. **高后果双钥匙规则**：
|
||||
- 仓库初始化及初始 main 分支保护由人类用户创建，禁止智能体自行关闭保护。
|
||||
Reference in New Issue
Block a user