diff --git a/docs/superpowers/specs/2026-10-16-stock-repos-adoption-matrix.md b/docs/superpowers/specs/2026-10-16-stock-repos-adoption-matrix.md new file mode 100644 index 00000000..a05e08b7 --- /dev/null +++ b/docs/superpowers/specs/2026-10-16-stock-repos-adoption-matrix.md @@ -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 试点
(PR #7 + Dev 两级分支 & triage)"] --> P2["Phase 2: Development-Manager 共享执行器对齐
(Runner Schema & Transport 统一)"] + P2 --> P3["Phase 3: Core & Backend 核心系统采纳
(两级分支 + AGENT-EXECUTION.md + admit)"] + P3 --> P4["Phase 4: Frontend, UI & 周边服务采纳
(设计门禁 + 执行门禁联动)"] + P4 --> P5["Phase 5: 共享叶子库全面接入
(无免死金牌，全代码库强制受控实施)"] +``` + +#### 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/`，日常小卡片切 `feature/-` 或 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 分支保护由人类用户创建，禁止智能体自行关闭保护。