@umacloud/knowledge 1.0.15 → 1.0.16

package/00-governance/knowledge-map.md

@@ -8,7 +8,7 @@ tags: [00-governance, knowledge, map]
 quality_score: 70
 last_updated: 2026-06-15
 ---
-# 开发：Excellent（11964948@qq.com）
+# knowledge-map
 
 ## 知识库地图（全环节）
 

package/agentic-delivery/01-standards/context-engineering-for-delivery.md

@@ -0,0 +1,94 @@
+---
+id: context-engineering-for-delivery
+title: 交付用上下文工程（恰当高度指令 + 即时检索 + 保真压实，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [context-engineering, right-altitude, just-in-time-retrieval, compaction, scratchpad-memory, sub-agent-isolation, context-rot, context-poisoning, context-overload, 上下文工程, 恰当高度, 即时检索, 压实, 外置记忆, 子代理隔离, 上下文腐化]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 交付用上下文工程（商业级必读）
+
+> 在长程交付里，**上下文是有限且会贬值的预算**，不是越塞越好。把整个代码库、整段历史、所有文档一股脑塞进去，换来的不是更聪明，而是**上下文腐化**（关键信息被淹没）、**上下文污染**（错误/过时信息被反复引用放大）、**上下文过载**（预算耗尽、注意力发散）。
+> 这份规范把"喂上下文"升级成可执行的**工程纪律**：指令写在**恰当高度**、信息**即时检索**而非预先堆砌、压实（compaction）必须**保真**（决策/改动文件清单/测试命令一个不能丢）、用**外置便笺记忆**减负、子代理**上下文隔离**只回小摘要。它和 `ai/ai-agent-memory-context-management`（产品侧记忆分层）、`agentic-delivery/01-standards/self-improving-memory-and-regression-sets`（跨次记忆演进）互补：本规范回答的是"一次长程交付里，上下文该怎么管才不贬值"。
+
+## 1. 上下文是预算：三种贬值与对策
+
+| 贬值形态 | 表现 | 对策 |
+|---|---|---|
+| 上下文腐化（rot） | 关键信息被海量无关内容淹没，注意力发散 | 只放当前步骤所需，按相关性裁剪 |
+| 上下文污染（poisoning） | 错误/过时/幻觉信息进了上下文并被反复引用放大 | 写入前校验来源、可追溯；发现污染即清并回退 |
+| 上下文过载（overload） | 预算耗尽、长尾信息挤占决策所需空间 | 即时检索 + 压实 + 外置记忆，控制驻留量 |
+
+原则：**最大化每一个 token 的信噪比**，而不是最大化塞进去的量。
+
+## 2. 恰当高度的指令（right-altitude）
+
+指令既不能太低（把每一步都写死成脆弱的硬编码流程），也不能太高（"做好它"这种无法执行的空话）：
+
+- **太低**：穷举式 if-this-then-that 脚本，环境一变就脆，且占满预算。
+- **太高**：只给愿景不给可判定边界，产出发散、无法验收。
+- **恰当**：给**目标 + 约束 + 验收标准 + 可用工具**，把"怎么做"的空间留给执行、把"做到什么算对"钉死。结构化需求与验收来自 `experts/product-manager/requirements-engineering-ears`。
+
+## 3. 即时检索（JIT）优于预先堆砌
+
+- **预先堆砌的代价**：把整个代码库/全部文档塞进上下文 → 信噪比塌陷、预算瞬间见底。
+- **即时检索**：按当前步骤的需要**临时取**最相关的切片（相关代码、相关契约、相关知识），用完即让其退出驻留。
+- **保留指针而非全文**：上下文里留"在哪能取到"（文件路径、检索入口）而非把全文常驻，需要时再拉。
+- **代码库切片**：用仓库地图/符号大纲给"够用的结构"而非全量源码，控制驻留体积。
+
+## 4. 压实（compaction）必须保真
+
+长会话逼近预算时要压实，但压实是**有损操作**，必须保住交付不可丢的事实：
+
+| 压实后必须保留 | 为什么 |
+|---|---|
+| 已做的关键决策与其理由 | 否则后续会推翻或重做已定方案 |
+| **已修改文件清单** | 否则丢失"改了哪些地方"，回归与收尾失准 |
+| **测试/构建/验证命令** | 否则无法重新验证，验收断链 |
+| 未决问题 / 待办 / 已知坑 | 否则同一个坑再踩一遍 |
+| 当前计划与下一步 | 否则上下文一压就迷失目标 |
+
+压实规则：宁可丢掉寒暄与探索弯路，**绝不丢决策、改动文件清单、验证命令**。压实是摘要不是清空。
+
+## 5. 外置便笺记忆（scratchpad）
+
+- 把超出当前必须驻留的信息**写到上下文之外**（便笺/文件/工作区产物），需要时再读回，给上下文减负。
+- 计划、决策记录、改动清单、验证结果落成**可寻址的外部产物**，而不是只活在易逝的会话里——这也让交付可审计、可恢复。
+- 这与跨次的自演进记忆衔接（见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`）：便笺是本次的工作记忆，演进记忆是跨次的长期沉淀。
+
+## 6. 子代理上下文隔离（只回小摘要）
+
+把发散的子任务（深度检索、批量扫描、探索性分析）交给**独立上下文**的子代理处理，主线只接收**精炼摘要**：
+
+- **隔离**：子代理在自己的上下文里展开海量中间过程，主线不被其噪声污染。
+- **小摘要回传**：子代理只返回主线决策真正需要的结论 + 证据指针，而非全部原始过程。
+- **预算守恒**：主线上下文始终保持高信噪比，长程任务不被单个子任务撑爆。
+
+## 7. 接入交付流程
+
+- **每步开始**：JIT 取该步所需切片，指令给在恰当高度。
+- **逼近预算**：压实，保住决策/改动文件清单/验证命令。
+- **发散子任务**：丢给隔离子代理，只收小摘要。
+- **持续**：关键状态外置成可寻址产物，污染即清并回退。
+
+## 8. 反模式（出现即不合格）
+
+1. **把整个代码库/全历史预先塞满**：信噪比塌陷、预算见底、决策被淹。
+2. **指令太低或太高**：脆弱硬编码流程，或"做好它"式空话，无法执行/无法验收。
+3. **压实丢掉决策/改动文件清单/验证命令**：回归失准、验收断链、方案被重做。
+4. **放任上下文污染**：错误/过时信息反复引用被放大，无人清除。
+5. **全文常驻不留指针**：该退出驻留的全文一直占着预算。
+6. **子任务不隔离**：探索噪声直接灌进主线，把主上下文撑爆。
+7. **关键状态只活在会话里**：一压实/一中断就全丢，不可恢复、不可审计。
+
+## 9. 最低交付 checklist
+
+- [ ] 指令写在恰当高度：给目标+约束+验收+工具，不写死脆弱流程、不留空话。
+- [ ] 按步骤即时检索相关切片，用仓库地图/指针替代全量常驻。
+- [ ] 压实保真：决策、已修改文件清单、测试/构建/验证命令一律保留。
+- [ ] 关键状态（计划/决策/改动清单/验证结果）外置为可寻址产物，可恢复可审计。
+- [ ] 发散子任务交隔离子代理，主线只接收精炼摘要 + 证据指针。
+- [ ] 上下文污染可检测：写入前校验来源，发现即清并回退。
+- [ ] 全程守住信噪比，预算用于决策所需信息而非长尾堆砌。

package/agentic-delivery/01-standards/eval-driven-delivery.md

@@ -0,0 +1,90 @@
+---
+id: eval-driven-delivery
+title: 评测驱动交付（黄金集由线上失败生长 + 轨迹评测 + 校准裁判 + pass^k 可靠性，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [eval-driven, golden-dataset, production-failures, trajectory-evaluation, tool-choice, judge-calibration, gold-set, pass-k, reliability, 评测驱动, 黄金集, 线上失败, 轨迹评测, 裁判校准, 可靠性]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 评测驱动交付（商业级必读）
+
+> "在几个演示样例上看起来对"不是交付证据。商业级交付要让**评测成为方向盘**：用会**随线上失败不断生长的黄金集**衡量真实质量、不只看最终答案而是**评测整条轨迹**（选了什么工具、参数对不对、走了几步、花了多少、有没有违规）、用**校准过的裁判**判主观项、对关键检查要求 **pass^k**（连续 k 次都对）的可靠性而非碰巧一次过。
+> 这份规范把评测从"跑个 demo"升级成可阻断的交付门，是 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`（回归集生长）在质量度量侧的延伸，与 `ai/agent-evaluation-benchmark`、`ai/02-playbooks/llm-evaluation-playbook`（产品侧评测体系）分工：本规范回答的是"凭什么相信这次交付是稳的，而不是恰好这次过了"。
+
+## 1. 黄金集：由线上失败生长，而非一次性手搓
+
+- **起点**：核心任务的代表性用例 + 已知边界与错误场景。
+- **生长**：每一个逃到线上的失败、每一个被抓到的回归，都**回灌**成黄金集里的一条新用例——评测集随真实失败单调变强，覆盖你真正会踩的坑。
+- **分层**：核心场景 / 边界场景 / 历史失败回归，按业务优先级分层维护。
+- **与回归集衔接**：项目级回归集（见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`）是黄金集中"必须永远对"的硬子集。
+
+## 2. 轨迹评测：不只看最终答案
+
+最终答案对、过程却荒唐（瞎调工具、绕一大圈、违反策略），在交付里同样是失败。要评**整条轨迹**：
+
+| 轨迹维度 | 评测点 |
+|---|---|
+| 工具选择 | 是否选了正确的工具/动作，而非碰运气堆调用 |
+| 参数有效性 | 工具调用的参数是否合法、符合契约、指向真实接口 |
+| 步数 / 效率 | 是否用合理步数达成，有无无意义绕路与重复 |
+| 成本 | token / 工具调用成本是否在预算内 |
+| 策略合规 | 是否触发越权、越界、违规操作（安全/权限/数据） |
+| 最终结果 | 产出是否满足验收标准 |
+
+原则：**结果正确是必要不充分条件**；轨迹的工具选择、参数有效性、合规性同样进评测，否则会奖励"歪打正着"。
+
+## 3. 校准裁判与裁判黄金集
+
+主观判定（"这个产出合不合格""需求满没满足"）若交给一个未经校准的裁判，等于换了把不准的尺子：
+
+- **裁判黄金集**：维护一组**已知正确标注**的样例（人工标定对/错），用来量裁判本身的准确率。
+- **校准**：裁判必须先在裁判黄金集上达到既定一致率，才允许用它判真实产出；裁判准则变更要重新校准。
+- **可解释**：裁判输出 pass/fail 要带证据（违反哪条标准），而非一句"感觉不行"，便于复核（呼应 `agentic-delivery/01-standards/verifier-critic-pattern`）。
+- **防漂移**：定期用裁判黄金集复测，发现裁判漂移即重校准。
+
+## 4. pass^k：关键检查要的是可靠，不是碰巧
+
+单次通过证明"可能行"，不证明"稳定行"。对**关键路径/高风险**检查，用可靠性口径：
+
+| 口径 | 含义 | 用在哪 |
+|---|---|---|
+| 单次通过 | 跑一次过 | 一般/低风险检查 |
+| **pass^k** | **连续 k 次独立运行全部通过**才算过 | 关键路径、支付/权限/数据完整性、不可逆操作 |
+
+- 关键检查要求 pass^k，把"偶尔过"挡在门外；k 随风险等级上调。
+- 与之配套：flaky（时绿时红）用例视为不可靠，必须先稳定或隔离（见 `testing/01-standards/ci-test-gates-and-coverage`），不允许靠重试蒙混过 pass^k。
+
+## 5. 评测作为交付门
+
+- **门禁阈值**：关键场景通过率不得低于阈值；关键检查满足 pass^k；安全/合规违规为零方可放行。
+- **回归触发**：实现、提示、工具、依赖任一变更都触发黄金集回归评测，趋势留痕。
+- **四维趋势**：质量、可靠性、成本、合规随交付批次上报，退化超阈值阻断。
+
+## 6. 接入交付流程
+
+- **建集**：核心 + 边界 + 历史失败回灌，维护裁判黄金集。
+- **评测**：每次关键变更跑黄金集；评轨迹不只评结果；主观项过校准裁判。
+- **判定**：关键检查 pass^k、违规为零、阈值达标才放行。
+- **生长**：线上失败与新回归回灌黄金集，评测集越用越强。
+
+## 7. 反模式（出现即不合格）
+
+1. **拿演示样例当交付证据**：几个 happy case 绿了就签字，不做标准化评测。
+2. **黄金集一次手搓后不再生长**：线上失败不回灌，评测集与真实风险脱节。
+3. **只评最终答案**：放过瞎调工具、违规操作、离谱成本的烂轨迹。
+4. **用未校准裁判判主观项**：尺子本身不准，判定不可信。
+5. **关键检查只看单次通过**：偶尔过被当成稳定，靠运气上线。
+6. **靠重试刷过 pass^k**：flaky 用例不修，用重试掩盖不可靠。
+7. **不跟踪成本与合规退化**：只盯正确率，安全/成本悄悄恶化。
+
+## 8. 最低交付 checklist
+
+- [ ] 黄金集覆盖核心 + 边界，并由线上失败与回归单调回灌生长。
+- [ ] 评测覆盖整条轨迹：工具选择、参数有效性、步数、成本、合规，不只最终答案。
+- [ ] 主观判定用经裁判黄金集校准的裁判，输出带证据、定期复测防漂移。
+- [ ] 关键路径/高风险检查要求 pass^k（连续 k 次全过），k 随风险上调。
+- [ ] flaky 用例先稳定或隔离，不允许靠重试蒙混过门。
+- [ ] 实现/提示/工具/依赖任一变更触发黄金集回归评测，四维趋势留痕。
+- [ ] 评测门阈值（通过率/pass^k/零违规）达标才放行，退化阻断。

package/agentic-delivery/01-standards/generated-code-failure-modes.md

@@ -0,0 +1,91 @@
+---
+id: generated-code-failure-modes
+title: 生成式代码失效模式目录（每一类失效配一条纠偏纪律，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [generated-code, failure-modes, happy-path-bias, silent-logic-failure, hallucinated-dependency, missing-system-context, performance-blindspot, missing-import, package-existence, 生成式代码, 失效模式, 沉默逻辑错误, 幻觉依赖, 系统上下文, 性能盲区, 缺失导入]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 生成式代码失效模式目录（商业级必读）
+
+> 生成式代码在演示里"能跑"，在生产里翻车，几乎总是因为同一批**可预测的失效模式**：只覆盖 happy path、把不在测试里的行为悄悄写错、引用不存在的依赖/接口、缺少系统约束（权限/限额/网络策略）、对性能毫无考虑、import 缺失却静默失败。这些不是随机 bug，是这一类产出的**结构性偏差**——可以逐条预判、逐条防住。
+> 这份规范把每一类失效配上**唯一能治它的纪律**：从"愿景式提醒"升级成"出现即不合格 + 配套防线"。测试侧的定向与回归纪律见 `agentic-delivery/01-standards/test-discipline-for-generated-code`，验证者解耦见 `agentic-delivery/01-standards/verifier-critic-pattern`，错误模型见 `backend/01-standards/error-handling-taxonomy`，供应链/依赖核验见 `security/01-standards/supply-chain-security`。本规范回答的是"生成式代码会怎么坏、对应要立哪条死规矩"。
+
+## 1. 失效模式 × 纠偏纪律（核心对照表）
+
+| 失效模式 | 典型表现 | 危险等级 | 纠偏纪律（唯一治法） |
+|---|---|---|---|
+| Happy-path / 错误处理偏差 | 只写成功路径，错误/边界/超时分支缺失或仅 `catch` 后吞掉 | 高 | 按错误分类法穷举失败路径并补错误分支用例 |
+| **沉默逻辑错误（最致命）** | 不在测试覆盖内的行为被悄悄写错，编译通过、跑得动、结果错 | **极高** | 用影响图把测试火力压到未覆盖行为 + 变异定向加固 |
+| 幻觉依赖/接口 | import 不存在的包、调用不存在的方法/参数、编造 API 形状 | 高 | 依赖与接口**存在性核验**（见 §3） |
+| 缺失系统上下文 | 漏权限(RBAC)、限额/配额、速率限制、网络/防火墙策略、多租户隔离 | 高 | 把系统约束作为显式输入清单注入并逐项验收 |
+| 性能无考量 | N+1 查询、循环内 IO、无分页/无索引、全量加载、无超时 | 中高 | 对热点路径做复杂度与容量审查 |
+| 静默缺失 import / 未用结果 | 漏 import 在动态语言里运行时才炸、函数返回值未被使用 | 中 | 静态检查 + 构建/lint 必过门禁 |
+
+判定原则：以上每一类**出现即不合格**；尤其"沉默逻辑错误"——它不报错、不崩溃、只是悄悄算错，是所有失效里最贵的一类。
+
+## 2. 沉默逻辑错误：为什么最致命，怎么防
+
+- **本质**：代码能编译、能运行、对演示输入看起来对，但对**没有被测试触及**的行为给出错误结果——没有任何信号告诉你它错了。
+- **防线**：
+  - 用代码↔测试影响图（见 `agentic-delivery/01-standards/test-discipline-for-generated-code`）把测试压到**未被覆盖的关键行为**上，而不是只测改了的那几行。
+  - 对核心逻辑做变异定向加固：注入你最怕的算错方式，要求有测试在它出现时变红。
+  - 用独立验证者只看 diff + 验收标准复核（见 `agentic-delivery/01-standards/verifier-critic-pattern`），抓"看起来对、其实需求没满足"的偏差。
+- **反例**：把货币四舍五入、时区换算、权限取反、分页 off-by-one 当成"反正测试绿了"——这些正是沉默逻辑错误的高发区。
+
+## 3. 幻觉依赖/接口：存在性核验是硬门
+
+生成式产出最常编造**不存在的包和方法**。把"存在性"当作可阻断门：
+
+- **包存在性**：每个新增依赖必须在锁定的来源里**真实存在且版本可解析**，不接受"看起来很合理"的包名（错别字/抢注风险，见 `security/01-standards/supply-chain-security`）。
+- **接口存在性**：调用的方法/参数/返回形状必须对照真实接口文档或类型定义核验，禁止凭记忆编 API 签名。
+- **版本锚定**：先确认已安装框架/库的**实际版本**，按该版本的 API 写代码，不按"通用印象"写（版本不符的签名是幻觉的重灾区）。
+- **构建即验证**：解析/编译/类型检查作为必过门，幻觉 import 在这里就该红。
+
+## 4. 缺失系统上下文：把隐性约束变成显式清单
+
+生成式产出默认不知道你的系统边界，必须把约束**喂进去并逐项验收**：
+
+| 约束类别 | 必须显式确认 |
+|---|---|
+| 鉴权与授权 | 谁能访问、RBAC/owner 校验、未登录/越权分支 |
+| 限额与配额 | 速率限制、配额、分页上限、批量上限 |
+| 网络与隔离 | 网络策略/防火墙、多租户数据隔离、出网白名单 |
+| 数据与合规 | 敏感数据处理、加密、保留与删除策略 |
+| 幂等与并发 | 重试安全、幂等键、并发写冲突 |
+
+这些不是"有空补"，是验收项；漏一项即视为缺失系统上下文失效。
+
+## 5. 性能盲区与静默缺失
+
+- **性能**：对热点路径审查 N+1、循环内 IO、缺分页/索引、全量加载、缺超时；至少给出复杂度量级判断，深度见 `development/performance-capacity-complete`。
+- **静默缺失**：漏 import、未使用返回值、未处理 Promise/错误，靠静态检查 + 构建/lint 门拦住（见 `testing/01-standards/ci-test-gates-and-coverage`），不留到运行时。
+
+## 6. 接入交付流程
+
+- **生成前**：把系统约束清单 + 已安装版本作为显式输入。
+- **生成后**：构建/类型检查/lint 必过拦截幻觉与静默缺失；依赖/接口过存在性核验。
+- **验证**：影响图 + 变异加固防沉默逻辑错误；独立验证者复核需求满足。
+- **沉淀**：每类被抓到的失效记入项目级回归集与经验库，防止重现。
+
+## 7. 反模式（出现即不合格）
+
+1. **只交付 happy path**：错误/边界/超时分支缺失或被吞掉。
+2. **放任沉默逻辑错误**："测试绿了"就签字，未覆盖行为悄悄算错无人发现。
+3. **引用幻觉依赖/接口**：装不存在的包、调编造的方法签名。
+4. **无视系统约束**：漏权限/限额/网络策略/租户隔离直接上。
+5. **对性能零考量**：N+1、循环内 IO、无分页/索引照单全收。
+6. **靠运行时才暴露静默缺失**：漏 import/未处理错误不被构建门拦住。
+7. **凭印象写 API 签名**：不核版本、不查接口，编造参数与返回形状。
+
+## 8. 最低交付 checklist
+
+- [ ] 每类失效模式都有对应防线，且"出现即不合格"写进验收。
+- [ ] 错误/边界/超时分支齐全并各有用例，不只覆盖 happy path。
+- [ ] 未被测试覆盖的关键行为有定向测试 + 核心逻辑变异加固，防沉默逻辑错误。
+- [ ] 新增依赖与调用接口过存在性核验，按已安装版本写、构建即验证。
+- [ ] 权限/限额/网络/隔离/合规作为显式约束清单逐项验收。
+- [ ] 热点路径过性能审查（N+1/分页/索引/超时）。
+- [ ] 漏 import/未处理错误被静态检查 + 构建/lint 门拦住，不留到运行时。

package/agentic-delivery/01-standards/production-readiness-scorecard.md

@@ -0,0 +1,79 @@
+---
+id: production-readiness-scorecard
+title: 分级生产就绪记分卡（Bronze/Silver/Gold：从可演示到商业级的可审计刻度，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [readiness-scorecard, bronze-silver-gold, graduated, maturity, demo-vs-commercial, tests-regression, contract, security, a11y, performance, observability, release-safety, 记分卡, 分级, 生产就绪, 可演示, 商业级, 可审计刻度]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 分级生产就绪记分卡（商业级必读）
+
+> "能跑的演示"和"敢卖的商业级产品"之间隔着一条线，而这条线长期是**说不清、争不出**的——每个人心里的"够好了"都不一样。这份记分卡把它变成**可审计的刻度**：跨 测试+回归、契约、安全、无障碍、性能、可观测、发布安全 七个维度，给出 **Bronze（最低可上线）→ Silver（生产稳健）→ Gold（加固）** 三档，**持续打分**，让"现在到底是 demo 还是商业级"一眼可判、可签字、可追责。
+> 它不是又一份逐条勾选清单，也不替代上线前的 go/no-go 决策——那是 `operations/01-standards/production-readiness-review`（PRR）。记分卡是**贯穿交付过程的连续分级**：PRR 在终点做一次放行判定，记分卡告诉你**此刻处在哪一档、离下一档还差什么**。各维度的权威标准在文内逐一指向，本规范回答的是"用什么刻度把 demo 和商业级区分开"。
+
+## 1. 三档的含义
+
+| 档位 | 定位 | 一句话判据 |
+|---|---|---|
+| **Bronze** | 最低可上线（minimum-shippable） | 核心流跑得通、错误不致命、能看见出没出事、能回退 |
+| **Silver** | 生产稳健 | 回归有兜底、契约对齐、关键安全/无障碍/性能达标、可观测齐全 |
+| **Gold** | 加固（hardened） | 高风险路径 pass^k 可靠、容量/容灾验证、发布安全闭环、审计完备 |
+
+原则：**档位取各维度的最低档**——任何一维只到 Bronze，整体就只是 Bronze。商业级交付的最低线是 **Silver**；Gold 留给关键系统与高风险路径。
+
+## 2. 七维 × 三档评分矩阵
+
+| 维度 | Bronze（最低可上线） | Silver（生产稳健） | Gold（加固） |
+|---|---|---|---|
+| 测试 + 回归 | 核心流有测试、构建/lint 绿 | 影响图定向覆盖、回归率为零、回归集进门禁 | 关键路径 pass^k、变异加固、独立测试作者 |
+| 契约 | 主要接口有定义 | 契约先行、前后端对照、错误模型统一 | 契约破坏在 CI 即红、版本与弃用策略闭环 |
+| 安全 | 鉴权到位、无明显高危、密钥不入库 | 授权(RBAC)/限额/输入校验齐、依赖存在性核验 | 供应链加固、SAST/扫描门、威胁面复核 |
+| 无障碍 | 核心流可键盘完成 | 对比度/焦点/语义达 AA、自动扫描 0 阻断 | 屏读端到端走查 + 回归断言 |
+| 性能 | 无明显 N+1/全量加载、关键页可用 | 热点路径达标、分页/索引/超时到位 | 容量/压测验证、预算守恒、退化阻断 |
+| 可观测 | 有日志、出错看得见 | 结构化日志 + 关键指标 + SLI/SLO | 告警/追踪/错误预算闭环、可定位根因 |
+| 发布安全 | 能回退 | 渐进发布 + 回滚预案演练 | 自动回滚触发、特性开关、变更可审计 |
+
+各维度权威标准：测试见 `agentic-delivery/01-standards/test-discipline-for-generated-code` 与 `testing/01-standards/ci-test-gates-and-coverage`；回归集见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`；契约见 `experts/architect/contract-first-api-design`、`testing/01-standards/contract-testing-and-api-contracts`；安全/供应链见 `security/01-standards/supply-chain-security`；无障碍见 `frontend/01-standards/accessibility-acceptance-gate`；可观测见 `observability/01-standards/observability-and-slo-operations`；发布安全见 `release-engineering/01-standards/progressive-delivery-and-release`；pass^k 见 `agentic-delivery/01-standards/eval-driven-delivery`。
+
+## 3. 持续打分，而非一次性盖章
+
+- **贯穿交付**：记分卡随交付过程持续更新，不是临上线才算一次。每次关键改动后重算受影响维度的档位。
+- **看板可见**：当前总档 + 各维度档位 + "离下一档差哪几项"明确列出，让"还差什么"可执行而非空谈。
+- **最低档决定总档**：短板维度直接拉低整体定位，逼着补齐而非用强项掩盖弱项。
+- **与 PRR 衔接**：上线前 PRR 做 go/no-go 时，记分卡是其输入证据之一——未达目标档即为 no-go 或有条件放行的依据。
+
+## 4. demo 与商业级的可审计分界
+
+- **demo = Bronze 以下或仅 Bronze**：能演示、不可托付生产。
+- **商业级 = Silver 起步**：有回归兜底、契约对齐、关键安全/无障碍/性能达标、可观测齐全、可回退。
+- **关键/高风险系统 = Gold**：pass^k 可靠、容量容灾验证、发布安全闭环。
+- 每次评级**留痕可审计**：档位、证据（哪条达标/未达标）、责任人、目标档与期限随交付归档。
+
+## 5. 接入交付流程
+
+- **立基线**：交付开始即声明目标档（一般 Silver，关键系统 Gold）。
+- **持续评**：每个关键步骤后重算受影响维度，更新看板与短板项。
+- **补短板**：以"离目标档差哪几项"驱动后续工作，最低档维度优先。
+- **放行**：达目标档 + PRR 放行才上线；未达即有条件放行（带遗留项/期限）或不放行。
+
+## 6. 反模式（出现即不合格）
+
+1. **用"差不多能跑"代替刻度**：没有可判定档位，demo 与商业级之争永远扯不清。
+2. **强项掩盖短板**：某维很亮就宣称商业级，无视有维度还在 Bronze。
+3. **临上线才评一次**：过程中不打分，问题堆到最后无法补。
+4. **记分卡不可审计**：只给个"已就绪"结论，无证据、无责任人、无期限。
+5. **把记分卡当 PRR 替代品**：用连续分级冒充上线放行决策，或反之。
+6. **目标档不声明**：不说要做到哪档，验收时各执一词。
+7. **达不到 Silver 就上商业生产**：无回归兜底/契约对齐/可观测/可回退强行交付。
+
+## 7. 最低交付 checklist
+
+- [ ] 交付开始声明目标档（商业级最低 Silver，关键系统 Gold）。
+- [ ] 七维（测试+回归/契约/安全/无障碍/性能/可观测/发布安全）各自评出档位。
+- [ ] 总档取各维最低档，短板维度优先补齐，不用强项掩盖弱项。
+- [ ] 记分卡持续更新、看板可见，明确列出"离目标档差哪几项"。
+- [ ] 每次评级留痕：档位 + 证据 + 责任人 + 目标档 + 期限，可审计。
+- [ ] 与 PRR 衔接：记分卡作为 go/no-go 的输入证据，未达目标档即拦或有条件放行。
+- [ ] 达不到 Silver 不交付商业生产；高风险路径要求 Gold。

package/agentic-delivery/01-standards/self-improving-memory-and-regression-sets.md

@@ -0,0 +1,80 @@
+---
+id: self-improving-memory-and-regression-sets
+title: 自演进记忆与本地回归集（增量增删演进 + 每个阻断项沉淀成回归用例，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [self-improving-memory, evolving-playbook, incremental-delta, context-collapse, regression-set, per-project, persisted-finding, dont-reintroduce, curation, 自演进记忆, 演进式手册, 增量增删, 上下文坍缩, 回归集, 阻断项沉淀, 不可重现]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 自演进记忆与本地回归集（商业级必读）
+
+> 一个团队如果每次交付都从零踩同样的坑，它就没有在变强。商业级交付要让**记忆变成一本随交付演进的手册**：每次只对它做**增量增删（delta）**，而不是整篇重写——整篇重写会触发**上下文坍缩**（把积累的细节抹平成一段越来越泛、越来越没用的概述）。同时，**每一个被抓到的阻断项都要沉淀成项目级的持久回归用例**，让下一次交付**无法把同一个缺陷再带回来**。
+> 这份规范定义记忆怎么演进、回归集怎么生长，是 `agentic-delivery/01-standards/context-engineering-for-delivery`（本次会话内的上下文管理）的跨次延伸，也是 `agentic-delivery/01-standards/test-discipline-for-generated-code`（回归率）与 `agentic-delivery/01-standards/eval-driven-delivery`（评测集生长）的记忆底座。它与 `ai/ai-agent-memory-context-management`（产品侧记忆分层）分工：本规范回答的是"交付经验怎么不丢、怎么不重蹈覆辙"。
+
+## 1. 记忆是演进的手册，不是一次性总结
+
+- **目标**：把"这个项目/这类任务怎么做才对、哪些坑会反复出现"沉淀成可检索、可复用、随时间变准的手册。
+- **可检索**：写入的每条经验带触发条件（技术栈指纹/场景/错误特征），让下次相关时能被精准召回，而不是大水漫灌。
+- **可解释**：召回时带命中理由与来源，便于判断是否适用、是否已过时。
+
+## 2. 增量增删（delta）演进，避免上下文坍缩
+
+记忆的更新方式决定它会越用越准还是越用越废：
+
+| 更新方式 | 结果 |
+|---|---|
+| 整篇重写/反复"总结再总结" | **上下文坍缩**：细节被磨平成泛泛概述，越改越没信息量 |
+| **增量增删（delta）** | 新增一条具体经验、修正一条过时项、删除一条被证伪项——主体稳定、细节累积 |
+
+规则：
+- 每次只追加/修正**与本次相关的具体条目**，不重写整本手册。
+- 过时或被证伪的条目**显式标注/删除**，而不是任其与新条目矛盾共存。
+- 保留**具体性**：一条"在 X 情形下因为 Y 会踩 Z，应当 W"远胜于"要注意质量"这种被反复总结磨平的空话。
+- 频率信号：同一类坑反复出现时升级为更高优先级的纠偏策略，而不是简单重复记录。
+
+## 3. 每个阻断项 → 项目级持久回归用例
+
+记忆不只是文字经验，更要变成**可执行的防线**：
+
+- **触发**：任何被确定性门或验证者抓到的**阻断级**问题（见 `agentic-delivery/01-standards/verifier-critic-pattern`）。
+- **沉淀**：为它生成一个**项目级持久回归用例**——把"重现这个缺陷的最小条件 + 期望的正确行为"固化成测试，存进该项目的回归集。
+- **不可重现**：此后任何改动若把同一缺陷带回来，该回归用例**立刻变红**，门禁拦截。被抓过一次的坑，下一次不允许再溜过去。
+- **配套经验**：同时在手册里记一条"此处易错、原因、规避"，让生成侧**事前避坑**，回归用例**事后兜底**，双保险。
+
+## 4. 回归集的本地性与生长
+
+| 性质 | 要求 |
+|---|---|
+| 本地（per-project） | 回归集属于具体项目，承载该项目特有的坑与契约，不是通用样例 |
+| 持久 | 进版本库随项目长期存在，不随单次会话消失 |
+| 单调生长 | 只增不轻易删；删除一条回归用例需明确理由（行为确实变更）并留痕 |
+| 进自动化门 | 回归集挂在 CI 必过门（见 `testing/01-standards/ci-test-gates-and-coverage`），每次改动都跑 |
+
+## 5. 接入交付流程
+
+- **抓到阻断项**：生成持久回归用例进项目回归集 + 手册记一条避坑经验（delta 增量）。
+- **下次交付**：相关时召回手册经验事前避坑；回归集在门禁兜底，重现即红。
+- **演进**：过时条目显式修正/删除，高频坑升级为纠偏策略，主体稳定、细节累积。
+- **留痕**：记忆与回归集的变更可审计，召回带理由与来源。
+
+## 6. 反模式（出现即不合格）
+
+1. **每次从零踩同样的坑**：阻断项修完即忘，不沉淀、下次重现。
+2. **整篇重写记忆**：触发上下文坍缩，手册越总结越泛、越用越废。
+3. **只记空话**："要注意质量/小心边界"这类无触发、无具体性的条目。
+4. **抓到的阻断项不变回归用例**：靠人记忆防回归，迟早再溜进去。
+5. **回归集不进门禁**：存了用例却不在 CI 跑，等于没有兜底。
+6. **过时条目放任矛盾共存**：新旧经验打架，召回时无法判断该信哪条。
+7. **回归用例随意删**：为了让构建变绿删掉碍事的回归用例（属反向作弊，见 `agentic-delivery/01-standards/test-integrity-and-anti-gaming`）。
+
+## 7. 最低交付 checklist
+
+- [ ] 记忆以增量增删（delta）演进，禁止整篇重写，保住条目具体性。
+- [ ] 每个被抓到的阻断项沉淀成项目级持久回归用例，重现即红。
+- [ ] 回归集进版本库、挂 CI 必过门，每次改动都跑。
+- [ ] 同步在手册记一条带触发条件的避坑经验，事前避坑 + 事后兜底双保险。
+- [ ] 过时/被证伪条目显式修正或删除，高频坑升级为纠偏策略。
+- [ ] 召回带命中理由与来源，可判断适用性与时效性。
+- [ ] 记忆与回归集变更留痕可审计；删除回归用例需理由不得为"凑绿"。

package/agentic-delivery/01-standards/spec-as-contract.md

@@ -0,0 +1,88 @@
+---
+id: spec-as-contract
+title: 规格即契约（自包含、点名文件接口、钉死范围与版本、内嵌坑、收尾带端到端验证，商业级必读）
+domain: agentic-delivery
+category: 01-standards
+difficulty: advanced
+tags: [spec-as-contract, self-contained, named-files-interfaces, out-of-scope, version-pinning, encoded-pitfalls, end-to-end-verification, living-spec, executable-spec, 规格即契约, 自包含, 点名文件, 范围, 版本锚定, 内嵌坑, 端到端验证, 活规格]
+quality_score: 95
+last_updated: 2026-06-29
+---
+# 规格即契约（商业级必读）
+
+> 一份"含糊的需求描述"换来的是含糊的实现。当交付由生成式执行时，规格不再只是给人读的说明，而是**给执行者的契约**——它必须**自包含**到：点名要改的文件与接口、明说**不做什么**、钉死版本、把已知的坑**写进去**、并以一条**端到端验证步骤**收尾。规格里没说清的，执行者就会自己猜，而猜出来的往往就是返工。
+> 这份规范定义"能直接执行的规格"长什么样，是 `experts/product-manager/requirements-engineering-ears`（把每条需求写成可验收句式）的工程化延伸——EARS 解决"单条需求怎么写得可验"，本规范解决"整份规格怎么自包含到可被直接执行、且随实现保持鲜活"。契约接口细节见 `experts/architect/contract-first-api-design`。本规范回答的是"一份规格要含到什么程度，执行者才不用猜"。
+
+## 1. 为什么规格要当契约写
+
+- **消除猜测**：执行者不在你脑子里。凡是规格没钉死的（哪个文件、什么接口、哪个版本、什么不做），都会被自由发挥，发挥的结果常与意图不符。
+- **可验收**：契约式规格自带"做到什么算对"，验收有据可依（呼应 `agentic-delivery/01-standards/verifier-critic-pattern` 的"只看 diff + 验收标准"）。
+- **可并行**：点名了文件与接口、明确了范围，多个工作面可并行而不互相踩。
+- **抗返工**：把已知坑写进规格，是把"事后踩坑"换成"事前规避"，最便宜的质量。
+
+## 2. 自包含规格的必含要素
+
+一份能被直接执行的规格，必须当场答全下面这些，缺一项就会变成猜：
+
+| 要素 | 要求 |
+|---|---|
+| 目标与背景 | 要解决什么问题、为什么、成功长什么样 |
+| **点名文件/模块** | 明确要改/要新增哪些文件、模块、目录，而非"在相关地方" |
+| **点名接口** | 涉及的函数/方法/API/契约签名与数据形状，按真实定义写 |
+| 验收标准 | 每条需求用可验收句式（见 EARS），含边界/错误/权限/并发 |
+| **明确不做（out-of-scope）** | 显式列出本次**不**覆盖什么，杜绝镀金与范围蔓延 |
+| **版本锚定** | 钉死框架/库/运行时的实际版本，按该版本 API 写 |
+| **内嵌已知坑** | 把这块历史上踩过、易错的点写进规格作为硬约束 |
+| 依赖与影响面 | 上下游依赖、数据/契约影响、迁移注意 |
+| **端到端验证步骤** | 收尾一条"怎么从头到尾证明它真的可用"的可执行验证 |
+
+## 3. 三个最常被略过、最该钉死的
+
+- **明确不做（out-of-scope）**：不写清楚不做什么，执行者就会顺手加未被要求的特性——这既是浪费也是风险（见 `agentic-delivery/01-standards/verifier-critic-pattern` 的过度设计护栏）。每份规格都要有一节"本次不包含"。
+- **版本锚定**：不锚版本，执行者会按"通用印象"写 API，版本不符即幻觉签名（见 `agentic-delivery/01-standards/generated-code-failure-modes`）。先确认已安装的实际版本，再按它写。
+- **内嵌已知坑**：把项目记忆里这块的高频坑（见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`）直接写进规格，让执行者事前避开，而不是又踩一遍再被回归集抓。
+
+## 4. 端到端验证步骤：规格的收尾即验收
+
+规格不能停在"实现完成"，要停在"怎么证明它对"：
+
+- **可执行**：给出从头到尾跑一遍核心流的具体步骤/命令（构建、启动、关键路径走查、断言），而不是"测一下"。
+- **覆盖关键路径**：端到端验证至少覆盖核心成功流 + 一条关键错误/边界流。
+- **与回归衔接**：端到端验证里暴露的问题沉淀成持久回归用例（见 `agentic-delivery/01-standards/self-improving-memory-and-regression-sets`）。
+- **作为完成定义**：端到端验证通过 + 验收标准满足 + 回归率为零，才算这份规格交付完成。
+
+## 5. 活规格（living-spec）维护
+
+规格不是写完即弃的一次性文档，它随实现保持鲜活：
+
+- **同步更新**：实现中发现规格与现实冲突（接口变了、范围调整、新坑），**先改规格再改代码**，不让规格与实现失同步。
+- **决策留痕**：规格里关键决策与其理由保留，避免后续推翻重做（与压实保真一脉相承，见 `agentic-delivery/01-standards/context-engineering-for-delivery`）。
+- **过时即修**：被证伪的约束显式修正，不放任过时条目误导后续。
+- **可寻址**：规格作为可寻址的交付产物存在（而非只活在会话里），可审计、可恢复。
+
+## 6. 接入交付流程
+
+- **动工前**：产出自包含规格（点名文件/接口、钉死范围与版本、内嵌坑、端到端验证步骤）。
+- **执行中**：规格与实现冲突时先改规格；执行者只按规格 + 验收标准做。
+- **收尾**：跑端到端验证步骤，达标 + 回归率零才判完成。
+- **沉淀**：验证暴露的问题进回归集，新坑回写进规格与记忆。
+
+## 7. 反模式（出现即不合格）
+
+1. **含糊需求当规格**："优化一下登录"这种，逼执行者全程猜。
+2. **不点名文件/接口**："在相关地方改"，执行者改错位置或漏改。
+3. **不写 out-of-scope**：放任镀金与范围蔓延，做了一堆没被要求的活。
+4. **不锚版本**：按通用印象写 API，版本不符即幻觉签名。
+5. **已知坑不写进规格**：让执行者把团队踩过的坑再踩一遍。
+6. **规格停在"实现完成"**：没有端到端验证步骤，无法证明真的对。
+7. **规格写完即弃**：实现改了规格不改，二者失同步、误导后续。
+
+## 8. 最低交付 checklist
+
+- [ ] 规格自包含：点名要改/新增的文件与模块，写清涉及的接口签名与数据形状。
+- [ ] 每条需求用可验收句式（EARS），含边界/错误/权限/并发。
+- [ ] 显式列出"本次不做（out-of-scope）"，杜绝镀金与范围蔓延。
+- [ ] 钉死框架/库/运行时实际版本，按该版本 API 写。
+- [ ] 把该模块已知高频坑内嵌进规格作为硬约束。
+- [ ] 规格以一条可执行的端到端验证步骤收尾（覆盖核心成功流 + 关键错误流）。
+- [ ] 活规格维护：实现冲突先改规格、决策留痕、过时即修，作为可寻址产物可审计。