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>
4.3 KiB
4.3 KiB
规则:验证优先 · 反"假绿"(机械门禁优先)
类型:硬约束(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 跑通后端 |
结论:这套环境不缺文档纪律,缺机械校验。所以本规则不写"应当",写"机械上做不到就不算数"。
二、硬规则(违反即缺陷)
- 完成的定义:一个 operation / 功能 / 旅程标记
completed必须有自动化绿证据(CI 实跑通过的单测/集成/端到端)。无证据只能needs_verification。禁止以手工台账数字作为完成的事实源。 - CI 必须真跑测试:门禁 job 禁用
-Dmaven.test.skip/skipTests;必须在项目真实 JDK(21)下编译+跑测试。新增模块的测试必须纳入 CI。 - 门禁断言"计算而非硬编码":禁止
assertEquals(<魔法数>, completed)这类被人工拨动的常量;完成数/状态必须从真实判据重新计算/扫描得出(参见muse-server/.../P1rApiCoverageReportTest,P0 已改造为 summary 自洽 + completed 必须引用磁盘真实存在的源码文件)。 - 三口径报完成,禁单一 %:对内对外只报 ① 代码实现度 ② 自动化验证度(CI 实跑通过数)③ 端到端可用度(真实形态跑通的旅程数)。禁止合并成一个"X% 完成"(合并数是高估来源)。
- 契约变更挂 CI 校验:接口/DB 契约改动必须有机械校验(
openapi-diff/flyway validate)在 CI 阻断,不能只靠"契约先行"的文档纪律。契约 SSOT =contracts/(建设中)。 - BC 边界由 ArchUnit 机械约束:模块不得
import他域.dal..(DO/Mapper)。跨 BC 只能走对外 API / facade-api 契约。已存在的违例(如 AI 模块直连 content DAL)登记为"已知违例 + 整改期",新违例一律 CI 阻断。(ArchUnit 规则建设中,见 rules/bc-boundaries) - 前端 mock 不算"已实现":MSW/mock 下的通过不构成可用证据。"可用"= 关该旅程 mock、对真后端、自动化端到端跑通(见 skills/golden-journey-vertical-slice)。
- 证据规则:区分"已验证事实 / 推断 / 假设";没有验证证据,绝不声称"完成/修复/通过/无问题"。能只读核实的先核实。
三、红线(立即视为缺陷,必须停下处理)
- 发现 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-diffCI;进度总账(done=自动化绿旅程)。
维护:本规则随机械门禁逐条落地而更新"已落地"清单;新发现的假绿形态追加进第一节并补对应门禁。