e181669197
本会话三部分交付,均经 JDK21 真实构建验证(非退出码,读 BUILD SUCCESS + Tests run):
1) Agent 开发基建(机械门禁优先)
- 入口与中枢:AGENTS.md、.agents/{knowledge,rules,skills,workflows}、CLAUDE.md 订正
- 订正 .gitignore:移除对 .agent/.agents 的忽略——它们是版本化 agent 基建,须入库(此前被忽略致克隆即缺)
- 机械门禁:CI 真跑测试(maven.yml JDK21、去 -Dmaven.test.skip)、覆盖台账去硬编码、
BC 边界 ArchUnit 门(BcBoundaryArchTest)、契约先行门(ContractFirstGateTest:Flyway 卫生 + OpenAPI 结构)
- 单一进度源 docs/mvp/进度总账.md + 7 个 BC per-module .agent + mise.toml(锁 JDK21)
- P1 增量:AiSuggestionMergeProjectionFacade(Gap A)、ContentSourceServiceImpl 事务化 outbox 回流(Gap B)
2) 过期历史文档清理(97 份 churn,git 可恢复)
- 删 docs/memorys(34)、agent-specs 审阅/执行版+迁移review(34)、superpowers/plans+specs(25)、
design-docs/临时+memorys(4);保留 superpowers/reports/coverage(门禁依赖)
- 唯一干货蒸馏入 .agents/knowledge/external-deps-and-gotchas.md;订正大纲/映射表/基线悬空引用
3) P1 harness 验证:消除已登记 BC 违例 ContentMuseWorkOwnerFacade
- content-api 新增只读端口 MuseContentWorkOwnerApi + content-server 实现(读自有 DAL);
AI 适配器改消费该端口、移除全部 content.dal 依赖,AI 业务规则与 4 消费者不变
- 删除 ArchUnit 豁免 → 门禁收紧(反向红 31 例 / 正向绿;适配器单测 13/0F、端口实现 7/0F)
注:muse-studio/src(SSE 相关 4 文件)与 muse-module-ai/pom.xml(移除孤儿 contract-server)
为本会话之前已存在的未提交改动,非本次工作,未纳入本提交。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
50 lines
4.3 KiB
Markdown
50 lines
4.3 KiB
Markdown
# 规则:验证优先 · 反"假绿"(机械门禁优先)
|
|
|
|
> **类型**:硬约束(rules) · **状态**:生效 2026-06-14 · **优先级**:最高(与本规则冲突的其它约定一律让位)
|
|
> **由来**:对抗复盘 `docs/agent-specs/2026-06-13-目标达成对抗复盘.md` 裁定本项目最深根因是 **「假绿」**——完成度信号可手工拨、CI 跳过测试、标签自填、前端 mock 假绿。现状基线见 `docs/agent-specs/2026-06-13-项目目标与模块现状基线.md`。
|
|
> **一句话**:**完成 = 机械验证通过,不是台账数字、不是自觉。** 软约束在本项目已被实证绕过,故一切约束以机械门禁为先。
|
|
|
|
---
|
|
|
|
## 一、为什么需要这条规则(已核实的"假绿"证据)
|
|
|
|
| 假绿形态 | 证据 |
|
|
|---|---|
|
|
| 完成度手工可拨 | 门禁测试曾硬编码 `assertEquals(147, completed)`,与 `p1r-api-coverage.json` 互相对着改(已于 P0 拆除) |
|
|
| CI 不跑测试 | `maven.yml` 曾用 `-Dmaven.test.skip=true` 跳过全部测试(已于 P0 移除);JDK 矩阵 8/11/17 ≠ 项目 21,主代码根本编不过(已订正为 21) |
|
|
| 标签自填 | 233 条 operation 的 `implementationStatus` 全人工填 `dedicated`,从未与代码机械核对 |
|
|
| live 验收自跳 | `*LiveAcceptanceIT` 全 `assumeTrue` 默认跳过 = 绿 |
|
|
| 前端 mock 假绿 | `muse-studio` DEV 无条件挂 MSW + `sse.ts` 契约漂移被 mock 喂成假绿,无人通过真实 UI 跑通后端 |
|
|
|
|
> 结论:这套环境**不缺文档纪律,缺机械校验**。所以本规则不写"应当",写"机械上做不到就不算数"。
|
|
|
|
---
|
|
|
|
## 二、硬规则(违反即缺陷)
|
|
|
|
1. **完成的定义**:一个 operation / 功能 / 旅程标记 `completed` 必须有**自动化绿证据**(CI 实跑通过的单测/集成/端到端)。无证据只能 `needs_verification`。**禁止以手工台账数字作为完成的事实源。**
|
|
2. **CI 必须真跑测试**:门禁 job 禁用 `-Dmaven.test.skip` / `skipTests`;必须在项目真实 JDK(**21**)下编译+跑测试。新增模块的测试必须纳入 CI。
|
|
3. **门禁断言"计算而非硬编码"**:禁止 `assertEquals(<魔法数>, completed)` 这类被人工拨动的常量;完成数/状态必须**从真实判据重新计算/扫描**得出(参见 `muse-server/.../P1rApiCoverageReportTest`,P0 已改造为 summary 自洽 + completed 必须引用磁盘真实存在的源码文件)。
|
|
4. **三口径报完成,禁单一 %**:对内对外只报 ① 代码实现度 ② 自动化验证度(CI 实跑通过数)③ 端到端可用度(真实形态跑通的旅程数)。**禁止合并成一个"X% 完成"**(合并数是高估来源)。
|
|
5. **契约变更挂 CI 校验**:接口/DB 契约改动必须有机械校验(`openapi-diff` / `flyway validate`)在 CI 阻断,不能只靠"契约先行"的文档纪律。契约 SSOT = `contracts/`(建设中)。
|
|
6. **BC 边界由 ArchUnit 机械约束**:模块不得 `import` 他域 `.dal..`(DO/Mapper)。跨 BC 只能走对外 API / facade-api 契约。已存在的违例(如 AI 模块直连 content DAL)登记为"已知违例 + 整改期",新违例一律 CI 阻断。(ArchUnit 规则建设中,见 [[rules/bc-boundaries]])
|
|
7. **前端 mock 不算"已实现"**:MSW/mock 下的通过**不构成**可用证据。"可用"= 关该旅程 mock、对真后端、自动化端到端跑通(见 [[skills/golden-journey-vertical-slice]])。
|
|
8. **证据规则**:区分"已验证事实 / 推断 / 假设";**没有验证证据,绝不声称"完成/修复/通过/无问题"**。能只读核实的先核实。
|
|
|
|
---
|
|
|
|
## 三、红线(立即视为缺陷,必须停下处理)
|
|
|
|
- 发现 verification theater:跳测试、硬编码门禁、手工拨完成度、`assumeTrue` 默认吞掉验收、mock 假绿当真。
|
|
- 为"让数字好看"而非"让用户能用"投入工时(如反复 `收口 X completed approval`)——已被 `docs/agent-specs/2026-06-13-P0-止血冻结令.md` 冻结。
|
|
|
|
---
|
|
|
|
## 四、已落地(本规则的首批机械门禁)
|
|
|
|
- ✅ P0:`maven.yml` 删 `skip` + JDK 矩阵→21 + 开 PR 门;`P1rApiCoverageReportTest` 去硬编码 147 → summary 自洽 + 文件存在性牙齿(23/23 绿,JDK21 实跑)。
|
|
- ✅ P0-2:收口刷分回路冻结令落档。
|
|
- ⏳ 待建:ArchUnit BC 边界门 [[rules/bc-boundaries]];`contracts/` SSOT + `openapi-diff` CI;进度总账(done=自动化绿旅程)。
|
|
|
|
> 维护:本规则随机械门禁逐条落地而更新"已落地"清单;新发现的假绿形态追加进第一节并补对应门禁。
|