Merge authoritative main into the task branch

Why: include the current integration baseline before verification. Evidence: fetched origin/main=682a4e8263fe007cb102fc9deaf71bda514ee387. Impact: integrate upstream changes without rewriting task history. Refs: task-sync
2026-10-17 05:39:39 +00:00
parent 1c10ddcd2e 682a4e8263
commit 2dec70e5ef
26 changed files with 4029 additions and 90 deletions
@@ -0,0 +1,81 @@
+# development-governance-v2 统一治理主记录
+
+本文件是治理大任务跨仓状态的唯一汇总。每行状态只取以下值之一，不用笼统的“完成”：
+`PLANNED / IMPLEMENTED / LOCALLY_VERIFIED / PR_OPEN / REVIEWED / GATE_PASS / MERGED / ADOPTED_ACTIVE / RELEASED / CLOSED`。
+通过类结论须带来源（GATE / REPLAY / SELF）与对象 SHA；历史对象证据不得充当当前 HEAD 证据。
+
+全局任务只有在全部正式仓达到 `ADOPTED_ACTIVE`、新项目入口启用、主 PR 全部合入并完成清理后才能标记 `CLOSED`。
+
+## 交付主线
+
+| Phase | 内容 | 仓库 / 分支 | PR | 状态 | 依赖 |
+|---|---|---|---|---|---|
+| 0 | 纠正候选状态、建立本主记录 | Dev `feature/development-governance-v2` | [#585](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/585) | IMPLEMENTED | — |
+| 1 | Guidelines 合同加固 | Guidelines `feature/development-governance-v2-contract-hardening` → `feature/development-governance-v2` | [#7](https://git-home.u1680832.nyat.app:30319/weichen/Development-Guidelines/pulls/7)（initiative→main） | PLANNED | — |
+| 2 | Dev triage 与两级生命周期整改（U2.1 远端发现与强制 triage；U2.2 即时目标完整性；U2.3 PR base 门禁） | Dev `feature/development-governance-v2-triage-hardening` → initiative | — | PLANNED | 1（合同） |
+| 3 | 真实两级 PR 演练 | Dev child PR → initiative → #585 → main | — | PLANNED | 2 |
+| 4 | Guidelines 合入 → Dev gitlink → Review → 三项 CI → 合入 #585 → 收口 | Guidelines / Dev | #7 / #585 | PLANNED | 1–3 |
+| 5 | Development-Manager 共享执行器 `agent-exec`；Dev Python 实现退役 | DM `feature/shared-agent-executor` | — | PLANNED | 4 |
+| 6 | 存量仓逐仓采纳 | 各仓独立 initiative | — | PLANNED | 5 |
+| 7 | 新项目治理初始化与 CI 准入 | DM | — | PLANNED | 5 |
+
+## 当前候选对象与历史证据
+
+| 仓库 | 分支 | 对象 | 证据 | 说明 |
+|---|---|---|---|---|
+| Development-Guidelines | `feature/development-governance-v2` | `ed4726c` | 无当前 Review/GATE | PR #7 open，未合入 |
+| Agent-System-Dev | `feature/development-governance-v2` | `611f855`（整改前）→ `e7e8ee0`（同步 main 后） | CI run 3417（对象 `9bc61ef`）、3419（对象 `611f855`）为历史对象证据 | PR #585 open，未合入；`accepting_requirements=false` 直至整改完成后按需重开 |
+
+## 已确认阻塞缺陷（整改前）
+
+1. Dev `task-triage` 按接纳中 initiative 数量直接给出 `JOIN`，不做适配判断（违反 KTD1）。
+2. Dev `task-triage` 只扫描当前检出的 `.task/`，看不到只存在于远端分支的 initiative（违反 KTD2）。
+3. `task-start KIND=child` 依赖本机已有父分支，未校验父 initiative 仍开放、接纳需求（违反 KTD3）。
+4. `task-start` 不要求 triage 收据；无 PR base 门禁；闭合记录与证据未贯穿 `immediate_target`。
+5. Guidelines 缺 terminal receipt 机器 Schema；配置 Schema 未覆盖 transport/admission/豁免/清理；`all-unavailable` 未与新项目准入隔离；triage 合同仍为数量判定。
+6. 原 U4 实施方式为 host 预写补丁交 CLI 应用，后续单元须由 CLI 自主实施。
+
+## 正式仓库清单与采纳矩阵
+
+来源：Gitea `/user/repos`（2026-10-16 实测）。排除：`Agent-System`（冻结参考仓，不再开发）、`SMDF-Agent-System`（空仓）、
+`governance-drill-2026-09` 与 `merge-queue-admission-fixture-20261014`（演练夹具）。本机 `*-wt-*`、备份与组合目录不计入。
+
+| 批次 | 仓库 | Guidelines 固定版本 | AGENT-EXECUTION.md | 共享执行器入口 | 正例 | 负例 | Review/CI | 状态 |
+|---|---|---|---|---|---|---|---|---|
+| A | Development-Guidelines | 自身 | — | — | — | — | — | PLANNED |
+| A | Agent-System-Dev | 待更新 | 有（本地 Python 控制器） | 待切换 | — | — | — | PLANNED |
+| A | Development-Manager | 待更新 | 无 | 实现方 | — | — | — | PLANNED |
+| B | Agent-System-Core | — | 无 | 无 | — | — | — | PLANNED |
+| B | Agent-System-Backend | — | 无 | 无 | — | — | — | PLANNED |
+| B | Agent-System-RDM | — | 无 | 无 | — | — | — | PLANNED |
+| C | Agent-System-Frontend | — | 无 | 无 | — | — | — | PLANNED |
+| C | Agent-System-UI | — | 无 | 无 | — | — | — | PLANNED |
+| C | Agent-System-Documents | — | 无 | 无 | — | — | — | PLANNED |
+| C | Agent-System-Releases | — | 无 | 无 | — | — | — | PLANNED |
+| D | Agent-Command | — | 无 | 无 | — | — | — | PLANNED |
+| D | Agent-Intent | — | 无 | 无 | — | — | — | PLANNED |
+| D | Agent-Native | — | 无 | 无 | — | — | — | PLANNED |
+| D | Agent-Squad | — | 无 | 无 | — | — | — | PLANNED |
+| E | Error-Code-System | — | 无 | 无 | — | — | — | PLANNED |
+| E | Logging-System | — | 无 | 无 | — | — | — | PLANNED |
+| E | Agent-Document-Renderer | — | 无 | 无 | — | — | — | PLANNED |
+
+## Owner 决策记录
+
+| 日期 | 决策 | 影响 |
+|---|---|---|
+| 2026-10-16 | cursor 服务端故障期间临时让 agy 成为首选；实际以不含 cursor 包装脚本的 PATH 启动执行器实现（停用 cursor profile 会使 Dev 参考解析器拒绝配置），cursor 冒烟恢复后回到正常 PATH | 无配置改动；收据中 cursor 如实记为 unavailable |
+| 2026-10-17 | 共享执行器分发：各正式仓像 Guidelines 一样固定 Development-Manager gitlink（`deps/development-manager`），薄入口 `scripts/agent-exec` 构建/运行该固定版本的 `dm-server agent-exec`；CI 用同一固定版本运行 `agent-exec validate` | Phase 6 每仓增加 DM gitlink 与薄入口；Dev Python 实现退役后同样切到该入口 |
+| 2026-10-17 | CI 读取私有 Guidelines/DM 子模块所需的 `SUBMODULE_TOKEN`：owner 授权智能体以 `~/.secrets/gitea` 的 API token 作为该 secret 值（只记录来源，不记录值） | 已为 Development-Manager 配置；Phase 6 按需为其他仓配置 |
+| 2026-10-17 | DM CI 自 2026-09-30 起从未成功（runner 无法拉取 github.com 上的 actions/checkout）；按 Dev 已审阅的内联检出模式改为自包含 CI（DM-U6） | Phase 6 中使用 `uses:` 的仓（Error-Code-System、Logging-System）同样需要检查 |
+
+## 停止条件
+
+无法获取权威远端 initiative；triage 收据与需求或候选 HEAD 不一致；child PR base 错误；Guidelines gitlink 未指向真实已合入版本；
+CLI 终态无效或副作用未知；Review、CI 或平台准入缺失；主干在最终 CI 后继续前进；存量仓无共享执行器却启用强制规则；
+需要发布规范 tag 而用户尚未执行双钥匙操作。出现任一项即停止对应交付窗口。
+
+## 用户双钥匙事项
+
+- Development-Guidelines 正式版本 tag：Agent 只准备命令，由用户执行。
+- 分支保护变更（如新增必需检查）：Agent 只准备方案，由用户执行。
@@ -0,0 +1,79 @@
+# 共享 Agent 执行器差异审计与架构归属（U3）
+
+## 一、背景与审计目的
+
+在推进“开发分支与 Agent 执行规范升级”（`development-governance-v2`）治理大任务中，核心要求之一是将 Agent CLI 执行约束由 Agent-System-Dev 的项目私有规则提升为 Development-Guidelines 的通用工程规范，并解决各仓库共享执行器的归属与复用问题。
+
+本审计针对当前已存在的两个主要实现进行差异比对：
+1. **Agent-System-Dev 控制器**：`scripts/agent_exec.py` + `scripts/agent_exec_adapters.py` + `scripts/agent_exec_config.py`；
+2. **Development-Manager 任务运行器**：`internal/runner/runner.go` + 相关适配器。
+
+目标是确定唯一所有者边界，避免在十几个仓库中复制代码，也不在通用规范库中塞入守护进程与语言特定绑定。
+
+---
+
+## 二、两套实现的详细比对
+
+| 维度 | Agent-System-Dev (`agent_exec.py`) | Development-Manager (`runner.go`) | 契约对齐与差距分析 |
+|---|---|---|---|
+| **调用模型** | 按需由 Host（CLI / Makefile / 脚本）调起的有界执行单元控制器 | 后台常驻守护进程，从 PostgreSQL 数据库轮询 `tasks` 记录并执行 | DM 属于异步平台运行器，Dev 属于交互式/本地工程单元执行器。两者面向阶段不同。 |
+| **配置权威** | 严格读取项目根目录 `AGENT-EXECUTION.md`，校验 schema 与角色路由 | 数据库中记录项目与任务信息，硬编码或配置注入 adapter 列表 | DM 未对接各项目独立的 `AGENT-EXECUTION.md` 配置。 |
+| **角色路由** | 支持 `implementation`、`repair`、`test`、`review` 四个独立角色候选列表 | 仅支持单一全局适配器列表遍历 | DM 缺乏按任务角色（实施/修复/测试/审查）精细路由的能力。 |
+| **候选轮换与重试** | 严格遵循候选顺序，每候选最多 3 次全新尝试；安全可恢复失败才换候选；全耗尽后支持一次 emergency profile | 尝试按序获取可用适配器，未实现针对 profile 的精确尝试计数与失败分类 | DM 缺少对失败语义的严格分流。 |
+| **失败分类与 Fail-Stop** | 细分为 `unavailable`、`failed-clean`、`failed-unknown`、`scope-expansion`、`blocked`、`cancelled`；未知副作用严格 fail-stop | 仅判断 err 是否为 nil，超时则记录预算耗尽，未提交改动记失败 | DM 未对未知副作用进行防扩散控制，缺乏 fail-stop 门禁。 |
+| **会话与进程隔离** | 每次尝试必为全新临时进程与工作区；禁止 `--continue`/`--resume` | 在 `.worktrees/` 下新建 worktree，但适配器内部进程管理由适配器各自实现 | 两者均采用独立 worktree，但 Dev 控制器对 CLI 命令行参数和 session flag 做了强制隔离。 |
+| **终态收据解析** | 实时消费事件流，严格从 CLI 原生信封（Cursor `result`、agy `result`/`json`、PI `message_end`）解码结构化收据 | 依赖适配器返回 `Receipt` 结构体，不校验底层事件信封篡改 | Dev 控制器的解码更防伪造，严格区分自然语言完成与结构化 completed。 |
+| **Git 权限与推送边界** | Worker 完全无 Git 推送与 PR 权限；通过受控 transport 快照集成，并由 pre-commit admit 校验 HMAC | Runner 代办 `gitPush` 并调用 Gitea API 创建 PR，但 Worker 需在 worktree 内完成 commit | DM 模型直接将 Worker 的 commit 推送到远端，缺少 Host 主动审查与 transport 完整性准入。 |
+| **Host Fallback** | `fallback_to_host: never`，安全耗尽后输出 `blocked`/`unavailable`，绝不代写业务代码 | 任务失败后将任务置为 `open` 或打标签，但未约束本地主协调者行为 | 通用规范要求明确禁止 Host 隐式代写。 |
+
+---
+
+## 三、架构归属与分工决策
+
+根据 Development-Guidelines 的要求与实现分离原则：
+
+```
+-----------------------------------------------------------+
+| Development-Guidelines (规范权威)                          |
+| - 核心规则硬边界 8 (Core Baseline MUST)                   |
+| - 通用 Agent 执行契约 (standards/agent-execution.md)        |
+| - 机器校验 Schema (templates/schemas/agent-execution.json)|
+| - 项目执行配置模板 (templates/AGENT-EXECUTION.md.template) |
+-----------------------------------------------------------+
+                              │ 规定合同与合格判据
+                              ▼
+-----------------------------------------------------------+
+| 共享工具层 (Development-Manager 或 独立执行控制器包)       |
+| - 可复用执行控制器 (Execution Controller)                 |
+| - 标准 CLI 适配器 (Cursor / Antigravity / PI / Codex)     |
+| - 事件流解码器与收据校验器 (Terminal Receipt Validator)   |
+| - 受控 Transport 打包器与 Admission 准入校验器             |
+-----------------------------------------------------------+
+                              │ 被各项目通过轻量入口调用
+                              ▼
+-----------------------------------------------------------+
+| 宿主项目仓库 (Agent-System-Dev / Core / Backend / ...)    |
+| - 项目根目录 AGENT-EXECUTION.md (角色、候选、超时、豁免)  |
+| - Makefile 薄封装 (make agent-exec-validate/apply/admit)  |
+| - 项目特有豁免路径与测试验证入口                           |
+-----------------------------------------------------------+
+```
+
+### 1. 为什么不将控制器直接放入 Development-Guidelines？
+Development-Guidelines 纯粹以文档、契约、schema 和规则为主，不依赖任何编程语言运行时（Python/Go/Node），也不包含守护进程。将几十页 Python 脚本或 Go 源码放入规范仓会破坏其轻量、项目无关和通用性。
+
+### 2. 为什么不把 Dev 的 `scripts/agent_exec.py` 复制到各个仓库？
+在 15 个以上的仓库中各复制一份 2700 行的 Python 脚本，会导致版本漂移、修复成本倍增和维护灾难。
+
+### 3. 工具层演进路径
+- **短期（当前试点期）**：以 `Agent-System-Dev` 中验证成熟的 `scripts/agent_exec.py`、`agent_exec_adapters.py`、`agent_exec_config.py` 作为黄金参考实现（Reference Implementation）。
+- **中期（共享工具化）**：将该控制器抽取为独立 CLI 工具（如 `agent-exec` CLI）或作为 `Development-Manager` 的底层执行子命令（`dm exec`），供本地协调者与 CI/CD 统一调用。
+- **长期（自动化闭环）**：`Development-Manager` 异步调度器在后台派发任务时，直接复用该底层执行内核，确保自动化派发与本地 Host 派发遵循完全一致的失败分流、收据解析与受控集成契约。
+
+---
+
+## 四、结论与验收判据
+
+1. **合同在先，实现对齐**：通用规范（Development-Guidelines）只约束合同（有界单元、会话隔离、收据格式、受控准入、禁止代写），不绑定具体语言实现。
+2. **工具符合性**：任何执行器（无论是 Dev 的 Python 脚本还是 DM 的 Go runner）必须通过相同的正负例验收判据（A8）才能声明为合规执行器。
+3. **消除隐式代写**：所有工具实现均必须支持 `fallback_to_host: never`，在候选耗尽时明确返回受阻终态，不得放行 Host 隐式撰写业务代码。
@@ -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 分支保护由人类用户创建，禁止智能体自行关闭保护。