@xulthekl/team-flow 0.64.0 → 0.65.0

package/skills/architecture-design/SKILL.md

@@ -22,7 +22,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 实体(唯一标识)+值对象(无标识)+聚合根(唯一入口)+事务边界(聚合内一事务)。聚合仅存于业务服务；数据服务/技术服务无聚合。
 
 ### F5 · 限界上下文(Context Map)
-语义边界=L3 应用服务；同术语异义须显式映射(Shared Kernel / Anti-Corruption Layer / Open Host Service)。
+语义边界=L3 应用服务；同术语异义须显式映射——**经典 8 模式**（Shared Kernel / Customer-Supplier / Conformist / Anti-Corruption Layer / Open Host Service / Separate Ways / Partnership / Published Language），选型走决策流（`references/context-map-8.md`，含 Mermaid；CML NO-GO）。
 
 ### F6 · CQRS 写读模型
 事务型对象→写模型(聚合，Command/Read 操作)；分析型对象→读模型(查询模型，Query 派生，无事务)。Command/Read→写模型；Query 经阻断测试分流。
@@ -37,7 +37,7 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - ch01-4a-domains — 4A 四域定义与分叉依赖
 - ch02-change-cascade — 变更级联与跨域一致性门禁
 - ch03-architecture-outputs — 架构产出三层 + 治理三支柱
-- ch04-entity-to-aggregate — 业务实体→聚合→限界上下文
+- ch04-entity-to-aggregate — 业务实体→聚合→子域→限界上下文
 - ch05-cqrs — 写/读模型、指令分流、三维判定
 - ch06-integration — 与 team-flow / compound-engineering 的集成
 
@@ -54,6 +54,11 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 - Command / Read / Query → ch05
 - 阻断测试 / 三维判定 → ch05
 - 增量设计 / As-Is 冻结 / 复利回写 / 全局锚点 → ch06
+- 子域 / 问题空间·解空间 / 统一语言索引 → ch04, 产品级模板 §0/§1.1（O2/O3）
+- Context Map 8 模式 / 决策流 / Mermaid → references/context-map-8.md（O7）
+- 事件 schema 版本策略 / 领域事件表 → 产品级模板 §3.2 门禁段 + 变更级模板 §2.5（O4）
+- Saga 补偿矩阵 / Projection 重建 / ADR 模板 → references/ddd-evented-playbook.md, references/adr-templates.md（O5/O6）
+- DDD 深度 advisory / ddd_depth（lightweight≠skipped）→ 「DDD 深度 advisory」段 + 结构化输出契约（O1）
 
 ## Workflow Integration: 判断+执行一体化（v0.9 §26）
 
@@ -67,10 +72,19 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 
 - `change-brief.md`（scope / AC / 技术方向）
 - `requirement/vN/plan.md` 高阶技术设计段（模块边界/技术选型/数据流/关键聚合划分）
-- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的唯一事实源；**Fast Path 下不读**（见 `### Fast Path`）
+- `docs/architecture/iterations/vN/architecture.md`（产品级架构快照，**设计期主输入**，v0.35.0）——BC 边界/聚合所有权/全局契约的设计输入（★ O8：**落地态权威 = 全局 ARCHITECTURE.md**（registry 渲染），快照 = grounding + seed 源 + 体检基准，不称唯一事实源）；**Fast Path 下不读**（见 `### Fast Path`）
 - 全局 `docs/architecture/`（As-Is 实际态基线，已落地部分）
 - 现有 `specs/`（若有）
 
+### DDD 深度 advisory（O1 · 在五项检查**之前**执行）
+
+按**领域复杂度**输出 DDD 深度旗标（advisory，**绝不替代 `decision`**）：
+
+- **三判据**（禁「4 选 2」硬阈值，防 LLM 套用偏差放大）：① 是否有丰富行为/不变量 ② 是否存在模型冲突（同词异义/多义） ③ 是否存在值得深建模的 Core Domain。
+- 输出 `ddd_depth: full | lightweight`。吸收「3 Questions + 反模式红牌」（微服务过早 / CQRS / 事件溯源 / DDD / Repository 可能过度工程）。
+- **★ 头号红牌：`lightweight ≠ skipped`**——lightweight 分支**仍须走完五项检查，且第 4/5 项（API / DB schema）不得短路**；只是战术建模从简（可省略部分 DDD 战术制品），判定与 API/DB 设计照做。
+- **诚实边界**：LLM 是否把 lightweight 误当"可跳过"**无法机械观测**——由契约正交 lint 与步骤表静态检查收敛路径，行为层保留人审（§10 风险如实登记）。
+
 ### 五项检查（架构变更判定）
 
 依次检查以下五项，**全部为否** → `decision: skipped`；**任一为是** → `decision: required`：
@@ -111,25 +125,23 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 **流程**（不硬阻断，显式确认 + 登记 deviation）：
 1. **呈现变更摘要**：涉及的产品级决策 + 影响范围（引用快照章节）
 2. **用户确认**（阻塞问题工具）：接受 → 执行变更；拒绝 → 保持产品级定义，change 内走增量
-3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
+3. **登记 deviation**：确认后写入 `orchestrator.yaml` 的 `replan_log`（`seq/trigger: arch-deviation/before/after/approved_by`——**可机读唯一落点**）；**Rationale/Consequences 按 `references/adr-templates.md` 选型**（五模板；仅「难逆转 ∧ 无上下文会困惑 ∧ 真实权衡」三条件全满足才写完整 ADR，否则 replan_log 一行即可，防泛滥；**不另起 `docs/adr/`**，防双轨漂移）+ 在 `iterations/vN/architecture.md` 演进日志追加修订记录（迭代收尾 S3.5 确认晋升）
 4. **`new` 聚合 flag**：在 `iterations/vN/architecture.md` 聚合注册表标注 `[pending-promotion]`，待下一迭代产品级晋升
 
 ### 执行流程
 
 ```
 1. 读取输入（brief + plan + specs + 全局 ARCHITECTURE.md）——**Fast Path 裁剪为「brief + precheck 输出」**
-2. 执行五项检查
-3. 全部为否：
-   → decision: skipped
-   → reason: 简述不涉及架构变更的理由
-   → 返回结构化输出
+1.5 DDD 深度 advisory（领域复杂度三判据 → ddd_depth: full | lightweight；advisory，不影响 decision）
+2. 执行五项检查（ddd_depth: lightweight 分支**同样执行全部五项**，第 4/5 项不得短路）
+3. 全部为否 → decision: skipped + reason（不涉及架构变更）→ 返回结构化输出（含 ddd_depth）
 4. 任一为是：
    → decision: required
    → reason: 简述涉及的架构变更项
-   → 执行完整 4A+DDD 增量设计（F1-F8）
+   → 执行 4A+DDD 增量设计（F1-F8；ddd_depth: lightweight 时战术制品从简，API/DB 产出不减）
    → 产出 architecture/architecture.md + database.md + api.md
    → artifacts: 产出路径列表
-   → 返回结构化输出
+   → 返回结构化输出（含 ddd_depth）
 ```
 
 ### 结构化输出契约
@@ -137,6 +149,8 @@ description: 基于 4A 企业架构 + DDD 领域驱动设计的架构/API/DB 设
 返回给 workflow-start 的结果**必须**包含以下字段：
 
 ```yaml
+ddd_depth: full | lightweight    # O1 advisory：与 decision **正交**——任意组合合法；
+                                 # 禁止从 lightweight 推导/默认出 skipped（契约正交 lint 锁定）
 decision: required | skipped
 reason: "..."                    # skipped 时：不涉及架构变更的理由
                                  # required 时：涉及的变更项摘要
@@ -146,6 +160,10 @@ artifacts:                       # required 时必填，skipped 时为空
   - architecture/api.md
 ```
 
+> **schema 正交（O1 判据①，规则文本 lint）**：`ddd_depth ∈ {full, lightweight}` 与 `decision ∈ {required, skipped}`
+> 同时存在、取值域独立、**任意组合合法**（lightweight+required / lightweight+skipped / full+required / full+skipped 全允许）——
+> schema 层**不得**出现 `lightweight → skipped` 的推导或默认值。该 lint 校验的是**我们写下的规则文本自洽**，不校验 LLM 实际判定（诚实边界见 advisory 段）。
+
 **职责边界**：architecture-design 负责**判断+产出**（五项检查判断是否涉及架构变更，涉及则产出架构设计文档），workflow-start 负责**reasonableness check + 状态写入**（确认判断合理性后写入 yaml）。
 
 ### 产出目录

package/skills/architecture-design/chapters/ch04-entity-to-aggregate.md

@@ -1,4 +1,4 @@
-# ch04 · 业务实体→聚合→限界上下文
+# ch04 · 业务实体→聚合→子域→限界上下文
 
 ## 业务实体（识别起点）
 - 定义：BA 流程中的**表证单书**（订单/合同/工单/客户档案/库存记录），是业务概念而非数据库表。
@@ -15,12 +15,23 @@
 - 事务边界：聚合内所有操作须在一个事务完成（如创建订单同时建头/行项目/算总价）。
 - **硬规则**：聚合仅存在于业务服务；数据服务（跨聚合查询分析）、技术服务（消息队列）**无聚合**。
 
-## 限界上下文 / Context Map（核心框架 F5）
-- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文。
-- 同术语异义须显式映射（映射类型）：
-  - **Shared Kernel（共享内核）**：两上下文共享部分模型。
-  - **Anti-Corruption Layer（防腐层）**：下游翻译上游模型，防止概念泄漏。
-  - **Open Host Service（开放主机）**：上游暴露标准协议供多下游消费。
+## 子域（问题空间 · 投资分级）
+- **子域(Subdomain)**：业务问题空间的分区（Vernon《IDDD》），先于解空间存在；子域 → 限界上下文是**多对多映射**（一个 BC 常服务多个子域），不是 1:1。
+- **三分类**：**Core**（核心竞争力，深建模）/ **Supporting**（保障性，最小定制）/ **Generic**（通用能力，买或复用）——**分类驱动 BC 投资**。
+- **纪律**：子域描述只写**业务问题**，不列 service / 包名 / 类名（问题空间 ≠ 解空间；按实现载体划子域/BC 是已知失效模式，须人审）。
+
+## 限界上下文 / Context Map（核心框架 F5 · 经典 8 模式，O7）
+- 限界上下文=语义边界，对应 L3 应用服务；相关聚合组成上下文（**解空间，≠ 子域**）。
+- 同术语异义须显式映射——**8 模式全集**（与产品级模板 §1.2 同步，教 = 用）：
+  - **Separate Ways**：不集成（先问要不要集成再选型）。
+  - **Partnership**：对等团队共同演进、双向承诺。
+  - **Customer-Supplier**：供需协商契约。
+  - **Conformist**：下游全盘接受上游模型。
+  - **Open Host Service**：上游开放标准协议供多下游消费。
+  - **Anti-Corruption Layer**：下游翻译上游模型，防止概念泄漏。
+  - **Shared Kernel**：两上下文共享部分模型，变更须协商。
+  - **Published Language**：标准化语义词汇（与 OHS 天然配对）。
+- **决策流与 Mermaid 生成**：见 `references/context-map-8.md`（选型顺序 Separate Ways → Partnership → Customer-Supplier → Conformist → OHS+PL → ACL → Shared Kernel；CML DSL 导出 = NO-GO）。
 
 ## 应用提示
 - 每变更设计先画"涉及实体的活动对象矩阵"；再定聚合根与事务边界；最后落到全局 Context Map。

package/skills/architecture-design/chapters/ch06-integration.md

@@ -6,8 +6,9 @@
 ```
 项目根/
 ├── STRATEGY.md              # 产品/BA 锚点（compound，不动）
-├── CONCEPTS.md              # 领域词汇（追加 DDD 术语，复利累积）
 ├── docs/architecture/       # 【技术锚点层，独立于 STRATEGY.md】
+│   ├── CONCEPTS.md          # ★ 业务统一语言唯一内容写入点（per-BC 业务术语定义）+ DDD 方法术语，复利累积
+│   │                        #   快照 §0 只是其 per-BC 索引（术语→锚点，不含定义）——零双写，见 O2
 │   ├── ARCHITECTURE.md      # 全局架构（瘦锚点：Context Map+聚合清单+关键决策）
 │   └── DATABASE.md          # 全局 DB（实体+读写模型+OLTP/OLAP）
 
@@ -28,13 +29,21 @@ changes/<name>/              # change 容器
 
 > **语义分离**：架构产出独立 `architecture/` 目录，不混入 `specs/`（行为规格）。目录存在 = 有架构产出，目录不存在 = 判定为不需要。下游消费方（spec-writer / release-archivist）显式读取此目录。
 
+## CONCEPTS.md 维护（O2 · 业务统一语言）
+
+- **两段拆分**：`docs/architecture/CONCEPTS.md` 内容组织分「**技术层角色词汇**」与「**per-BC 业务统一语言**」两段——技术分层角色（infra / agg / adapter / bff 等）**不是领域词**，不得混入业务段（消 emp-auth 审计 B6/B7 技术 jargon 污染）。
+- **主动纪律（活的语言，非静态表）**：① **挑战术语**——业务术语首现即问"业务方听得懂吗"；② **锐化模糊语**——歧义词当场拆义项，不带病累积；③ **场景压测**——拿真实业务场景验证术语覆盖度；④ **对照代码**——术语与代码标识符互查漂移（LLM 生成的 UL **必须人审**，防幻觉领域概念）。
+- 快照 §0 只维护索引（per-BC 术语 → 锚点）；本文件的更新触发时机靠流程纪律（**无机械门禁**，方案 CQ-12 已登记），由迭代收尾人审把关。
+
 ## 每变更增量设计（SOP 步骤，v0.35.0 更新：产品级快照为输入）
-1. (LLM) 读全局 ARCHITECTURE.md **+ 产品级快照 `iterations/vN/architecture.md`**（v0.35.0，BC 边界/聚合注册表唯一事实源）作 grounding；识别本 change 触及的 BC → 按 `references/s3.5-loading-protocol.md` 三段式装载对应域；用活动对象矩阵识别限界上下文/聚合（变更级只引用产品级注册表，不重定义）。
+1. (LLM) 读全局 ARCHITECTURE.md **+ 产品级快照 `iterations/vN/architecture.md`**（v0.35.0 作 grounding；★ O8 修正：**落地态权威 = 全局 ARCHITECTURE.md marker 区**（registry 渲染、source 列归因），快照承担 grounding + 首次 seed + 差异体检基准三角色——**不再称"唯一事实源"**，forward-designed 快照是预测态）；识别本 change 触及的 BC → 按 `references/s3.5-loading-protocol.md` 三段式装载对应域；用活动对象矩阵识别限界上下文/聚合（变更级只引用产品级注册表，不重定义）。
 2. (LLM) 出 To-Be：**本 change 增量**（extend/new/refactor 三类动作）——新增/调整聚合、Context Map 关系、CQRS 读写模型、4A 跨域对齐；触及产品级决策走架构修订决策门。
 3. **As-Is 冻结**（核心修正）：复制产品级快照/全局相关章节**当前原文** + 记版本锚点（`iterations/vN/architecture.md@<change_id>#<章节>`），变更内不可变——杜绝活引用漂移。
 4. (脚本) 填 frontmatter 并校验：`cap_id/date/change_type/bounded_contexts/aggregates_affected/cqrs`。
 5. (LLM) 写 ADR 理由；API 标 Command/Read/Query + 阻断测试归属。
-6. (脚本) 回写全局 + 生成 API 索引。
+6. (LLM→脚本) **O8 两段式回写**：先（LLM 语义段）从本 change 制品产 `architecture/.arch-delta.json`
+   （new/extend/refactor/retire + evidence，见 release-archivist ①-pre）；再（CLI 确定段）`tf arch-merge`
+   消费该制品合并进 `docs/architecture/.registry/registry.json` 并生成全局产物（确定段零 LLM，可重放）。
 
 ## 复利回写（借鉴 ce-compound，已正名）
 - **one change per run**：一次回写一个变更 delta，可追溯、不混杂。

package/skills/architecture-design/glossary.md

@@ -1,6 +1,10 @@
 # Glossary · 架构设计术语表
 
+> **本表是方法论术语表**（4A / DDD 概念），**不是业务域统一语言**——per-BC 业务术语的唯一内容写入点是 **`docs/architecture/CONCEPTS.md`**（根位置自 v0.23.0 已弃用），快照 §0 只是其索引（O2）。
+
 - **BA / IA / AA / TA**：业务/信息(数据)/应用(功能)/技术 架构四域。仅 TA 是技术架构。
+- **子域(Subdomain)**：业务**问题空间**的分区，先于解空间存在；Core/Supporting/Generic 三分类驱动投资。
+- **问题空间 / 解空间**：问题空间 = 业务问题与子域（做什么）；解空间 = 限界上下文与聚合（怎么做）。子域 → BC 多对多映射，**不是 1:1**；按实现载体（service/包）划子域是已知失效模式。
 - **分叉依赖**：`BA→(IA∥AA)→TA`，BA 先行、IA/AA 并行双向对齐、TA 最后。
 - **跨域一致性（双对齐）**：AA 功能≥1 IA 实体支撑，IA 实体≥1 AA 功能消费；结构+语义双对齐。
 - **架构产出三层**：元素(积木)/制品(图纸)/交付件(成品)。
@@ -9,7 +13,7 @@
 - **聚合(Aggregate)**：实体+值对象+聚合根+事务边界；仅存业务服务。
 - **聚合根(Aggregate Root)**：聚合外部唯一入口。
 - **值对象(Value Object)**：无独立标识，属性变即另一对象。
-- **限界上下文(Bounded Context)**：语义边界，对应 L3 应用服务。
+- **限界上下文(Bounded Context)**：语义边界，对应 L3 应用服务；属**解空间**，不等于子域。
 - **Context Map**：限界上下文间关系图；映射类型 Shared Kernel / Anti-Corruption Layer / Open Host Service。
 - **CQRS**：写模型(事务型,聚合)与读模型(分析型,查询模型)分离建模。
 - **写模型(Write Model)**：事务型对象在 AA 的表达，有聚合根/事务边界，Command/Read 操作。

package/skills/architecture-design/references/adr-templates.md

@@ -0,0 +1,56 @@
+# ADR 模板库 + deviation 登记接入（O6）
+
+> **定位**：ADR 是**架构修订决策门 deviation 登记的 Rationale/Consequences 载体**，
+> **不另起 `docs/adr/` 目录**（防双轨漂移——可机读登记唯一落点 = `orchestrator.yaml:replan_log`）。
+> `adr-tools` / PR 流程属 git 流程，**映射进 replan_log 而非照搬**。
+
+## 何时写（Offer ADRs sparingly · 三条件，全部满足才写完整 ADR）
+
+1. **难逆转**（改回代价高：BC 边界 / 聚合所有权 / 全局契约 / 存储选型）；
+2. **无上下文会困惑**（后来者不读会重新争论同一问题）；
+3. **真实权衡**（存在过实质备选方案，而非显然选择）。
+不满足 → 只在 `replan_log` 留一行（trigger/before/after/approved_by 已足够），**不产出 ADR 文件**。
+
+## 五模板（按场景选一）
+
+### 1. MADR（完整决策记录）
+```markdown
+# ADR-<seq>: <决策标题>
+## 状态 <提议|采纳|废弃|被 <ADR> 取代>
+## 背景 <forces：约束与压力>
+## 决策 <我们选择…>
+## 后果 <正 | 负 | 风险>
+```
+
+### 2. 轻量（默认首选）
+```markdown
+ADR-<seq>: <标题> — 采纳 <date>
+背景：<一句>；决策：<一句>；后果：<正/负各一句>
+```
+
+### 3. Y-Statement（单句形）
+```markdown
+<境况>，我们采用 <方案> 来满足 <驱动>，以换取 <正果/代价>，由 <人/机制> 复审。
+```
+
+### 4. 废弃记录
+```markdown
+ADR-<seq> 已废弃（<date>，<原因>）。原决策见 replan_log seq=<n>；替代 = <新决策或「无」>。
+```
+
+### 5. RFC（须广泛评审的难逆转决策）
+```markdown
+RFC-<seq>: <标题> — 提议 <date>；问题 / 备选方案（≥2）/ 推荐 / 评审人 / 结论
+（评审结论仍须回写 replan_log——机读登记不在 RFC 内闭环）
+```
+
+## 与 replan_log 的映射（O6 判据：变更级 ADR/偏差登记落到可机读处）
+
+| replan_log 字段 | ADR 对应 |
+|---|---|
+| `seq` / `trigger: arch-deviation` | ADR-<seq> / 状态行 |
+| `before` / `after` | 背景 forces → 决策（改动前后） |
+| `approved_by` | 状态：采纳 |
+| （Rationale/Consequences 正文） | ADR 正文——**存于 change 制品或演进日志，replan_log 只存指针与摘要** |
+
+**防泛滥**：一次决策门默认产出 = replan_log 一行；三条件全满足才升级为完整 ADR。

package/skills/architecture-design/references/context-map-8.md

@@ -0,0 +1,47 @@
+# Context Map · 经典 8 模式与决策流（O7）
+
+> 产品级快照 §1.2 与变更级 Context Map 变更的**选型参考**（内联 reference，红牌 4：不引外部路由壳）。
+> 教学同步：ch04「限界上下文 / Context Map」节与本文件同源（教 = 用，消除 3 vs 8 漂移）。
+
+## 8 模式全集
+
+| # | 模式 | 一句话语义 | 典型信号 |
+|---|------|-----------|---------|
+| 1 | **Separate Ways** | 两上下文各走各的，不集成 | 集成成本 > 收益；无共享语言需求 |
+| 2 | **Partnership** | 两团队共同演进、双向承诺 | 对等团队、共同目标、长期协作 |
+| 3 | **Customer-Supplier** | 上游供能力、下游提需求，协商契约 | 明确的供需方；契约可谈 |
+| 4 | **Conformist** | 下游全盘接受上游模型，放弃翻译 | 上游强势/模型稳定；翻译不划算 |
+| 5 | **Open Host Service** | 上游开放标准协议供多下游消费 | 对外开放能力；多下游 |
+| 6 | **Anti-Corruption Layer** | 下游建防腐层翻译上游概念 | 上游模型脏/惯性大；须隔离污染 |
+| 7 | **Shared Kernel** | 两上下文共享部分模型，变更须协商 | 高度耦合的核心域子集；小团队 |
+| 8 | **Published Language** | 标准化语义词汇，跨组织共享语言 | 与 OHS 天然配对；外部伙伴消费 |
+
+**PL 与 OHS 配对**：OHS 给协议形状，PL 给语义词汇——只有 OHS 无 PL 时下游仍需猜测语义（配对使用，计数上仍是两个独立模式）。
+
+## 决策流（选型顺序：从"不集成"到"深耦合"）
+
+```mermaid
+flowchart LR
+  A[需要集成吗?] -->|否| SW[Separate Ways]
+  A -->|是, 对等团队| P[Partnership]
+  A -->|是, 有供需| CS[Customer-Supplier]
+  CS -->|下游愿受制| CF[Conformist]
+  CS -->|须隔离污染| ACL[Anti-Corruption Layer]
+  CS -->|对外开放/多下游| OHS["OHS + Published Language"]
+  A -->|核心域共享子集| SK[Shared Kernel]
+```
+
+**决策纪律**：① 先问"要不要集成"再选模式；② 关系类型写进产品级快照 §1.2 表的「关系类型」列（8 选 1）；
+③ 变更级 context_map 条目经 `.arch-delta.json` 登记（kind=context_map，pattern 枚举即本表 8 项，宿主 fields.source_bc）；
+④ **CML（Context Mapper DSL）导出 = NO-GO**（工具锁定、ROI 低）——图用 Mermaid。
+
+## Mermaid 生成（扩产品级 §1.2 既有图）
+
+```mermaid
+flowchart LR
+  order -->|C-S| payment
+  payment -->|"OHS+PL"| partner
+  downstream -.->|ACL| upstream
+```
+- 关系标注取模式缩写：SK / C-S / Conf / ACL / OHS+PL / SW / Partner。
+- 跨域 ≥3 BC 时按「受影响优先级」分步细化（守加载预算，见 s3.5-loading-protocol.md）。

package/skills/architecture-design/references/ddd-evented-playbook.md

@@ -0,0 +1,41 @@
+# DDD 事件化设计手册 · Saga 补偿与 Projection 重建（O5）
+
+> **设计层 ONLY（红牌 2）**：本文件只产矩阵/策略/表格进架构产物，**绝不生成可执行代码**。
+> 补偿逻辑、幂等键、重建步骤须**人审**（AI 仅出草案）。边界：聚合内事务 ≠ 跨聚合 saga
+> （聚合状态机在产品级 §4，saga 不得画进聚合状态机）。
+
+## 1. 命令 / 查询分离（为什么跨聚合最终一致）
+
+- Command 侧：单聚合事务内强一致（聚合根守护不变量）；跨聚合**不共享事务**。
+- Query 侧：读模型由事件投影派生（CQRS），可异步、可最终一致、可按视图重构。
+- 判据：需要跨聚合强一致？→ 先质疑建模（多半该合并聚合或改流程）；确实要 → Saga 编排补偿，不拉分布式事务。
+
+## 2. Saga 补偿矩阵模板（变更级/产品级 §4 附表）
+
+| 步 | 参与聚合/BC | 正向动作 | 触发事件 | 补偿动作 | 超时策略 | 幂等键 | 失败升级 |
+|----|------------|---------|---------|---------|---------|--------|---------|
+| 1 | order:Order | PlaceOrder | OrderPlaced | CancelOrder（未支付可撤） | 5s | orderId+step | 人工介入 |
+| 2 | payment:Payment | Charge | PaymentCaptured | Refund | 10s | paymentId+step | 重试≤3 后告警 |
+
+填写纪律：每个正向动作**必须**有补偿列（不可补偿 → 显式标「人工兜底」，不留空）；超时与幂等键必填。
+
+## 3. Projection 重建策略（读模型灾备）
+
+1. **先在 staging 重建再切生产**——禁止直接对生产读模型做全量重放。
+2. 重建源 = 事件存储/发件箱全量 + 水位标记；重建过程幂等（同幂等键重复消费无副作用）。
+3. 重建后做**对账**（写模型聚合数/关键计数 vs 读模型投影）→ 差异清零才切流。
+4. 重建属运维剧本：进 `docs/` 运维文档或 ADR，**不进代码库生成**。
+
+## 4. 幂等键与事件版本化
+
+- 幂等键 = `业务主键 + 步骤/事件类型`（消费侧登记已处理键；重复投递直接 ACK）。
+- 事件版本化：**门禁见产品级快照 §3.2（O4）**——major/minor/tombstone + 消费侧 upcasting；
+  本手册不重复定义，只约束「saga 步骤引用的事件必须是已定版事件」。
+
+## 5. 产物落点
+
+| 产物 | 位置 |
+|------|------|
+| Saga 补偿矩阵 | 变更级 `architecture.md` §4 附近 或 产品级快照 §3 附表 |
+| Projection 重建 | 同上（策略段）+ 运维文档引用 |
+| registry 登记 | 事件经 `.arch-delta.json` kind=event（宿主 fields.owner_aggregate） |

package/skills/architecture-design/references/s3.5-architecture-template.md

@@ -1,6 +1,6 @@
 # S3.5 产品级架构文档模板（v0.35.0，v0.14 §60）
 
-> 产品级架构设计（architecture 阶段）产出的权威文档模板。基于 4A + DDD 方法论，覆盖 6 类产物。
+> 产品级架构设计（architecture 阶段）产出的权威文档模板。基于 4A + DDD 方法论，覆盖 6 类产物（+ §0 统一语言索引 / §1 子域-BC 拆分的结构增强，产物计数不变）。
 > 位置：`docs/architecture/iterations/vN/architecture.md`（预测态快照，P1：不写全局当前态）。
 > 产出后须经产品级评审门（architecture-reviewer product 视角）PASS 才进 S3（2026-08-19：ARCH 上移 S3 前，原"进 S4"）。
 
@@ -16,7 +16,31 @@ superseded_by: null                # 下一版快照路径（退役时填）
 ---
 # 产品级架构设计 · 迭代 vN
 
-## 1 限界上下文（Context Map）          <a id="bc"></a>
+## 0 统一语言索引（per-BC）            <a id="ul"></a>
+
+> **唯一内容写入点 = `docs/architecture/CONCEPTS.md`**（业务统一语言；根位置自 v0.23.0 已弃用）。本节**只放索引**（术语 → 锚点），**不含定义内容**——零双写、零漂移；业务语言不进 registry（非架构结构）。
+> **预算**：本节约 ~150 token，计入加载协议 ~2K 总预算（人审把关，无机械校验——见 s3.5-loading-protocol.md）。
+> **日期锚门控**：存量快照（`established_at` < 2026-09-25，**或 `established_at` 缺失/不可解析**）无本节**或无 §1.1 子域段** → 评审 WARN 不 FAIL（存量不追溯）。
+
+| 所属 BC | 术语 | 详情锚点 |
+|---------|------|----------|
+| order | 客户=下单人 | docs/architecture/CONCEPTS.md#order |
+| payment | 客户=付款人（同词异义） | docs/architecture/CONCEPTS.md#payment |
+
+## 1 子域与限界上下文                 <a id="bc"></a>
+
+### 1.1 子域（问题空间 · 投资分级）
+
+| 子域 | 分类 | 业务问题（一句话，与实现载体脱钩） |
+|------|------|-----------------------------------|
+| 订单履约 | Core | 下单-支付-发货全链路，核心竞争力所在 |
+| 结算对账 | Supporting | 保障性工作，最小定制即可 |
+| 基础数据 | Generic | 通用能力，买或复用 |
+
+> **分类驱动投资**：Core 深建模 / Supporting 最小定制 / Generic 买或复用（Vernon《IDDD》问题空间纪律）。
+> **纪律**：子域描述只写**业务问题**，**不列 service / 包名 / 类名**（问题空间 ≠ 解空间；按实现载体划子域是已知失效模式）。
+
+### 1.2 限界上下文（解空间 · Context Map）
 
 | 上下文 | 职责(一句话) | 依赖 | 关系类型 | 语言边界/关键术语 |
 |--------|------------|------|---------|-----------------|
@@ -30,7 +54,7 @@ flowchart LR
   order -->|C-S| stock
 ```
 
-**关系类型枚举（6 种）**：Shared Kernel / Customer-Supplier / Conformist / Anti-Corruption Layer / Open Host Service / Separate Ways。
+**关系类型枚举（经典 8 模式，O7）**：Shared Kernel / Customer-Supplier / Conformist / Anti-Corruption Layer / Open Host Service / Separate Ways / **Partnership** / **Published Language**（PL 与 OHS 天然配对）。选型走**决策流**（Separate Ways → Partnership → Customer-Supplier → Conformist → OHS+PL → ACL → Shared Kernel）——详见 `references/context-map-8.md`（含 Mermaid 生成指引；CML DSL 导出 = NO-GO）。
 
 ## 2 聚合注册表                        <a id="aggregates"></a>
 
@@ -64,6 +88,12 @@ flowchart LR
 | OrderPlaced | 领域 | order:Order | PlaceOrder | orderId, items | payment, stock | order-summary-view |
 | PaymentCaptured | 集成 | payment:Payment | 支付回调 | orderId, paymentId | order:Order | order-summary-view |
 
+> **事件 schema 版本策略门禁（O4）**：事件化场景**必填版本字段**（缺失 → 评审阻塞，不放行）——
+> **major** = breaking（删字段/改语义，消费方必挂）：须提供 upcasting 迁移路径；**minor** = 加可选字段（向后兼容）；
+> **tombstone** = 退役事件显式标记（禁静默消失，同红牌 6）。版本一经发布**只增不改**；
+> upcasting 在**消费侧**做（读入旧版本事件时升格），生产侧不重写历史（依据「Version events from day one」）。
+> 事件条目经 `.arch-delta.json`（kind=event，`fields.owner_aggregate` 挂宿主）登记进 registry.events 载体。
+
 ### 3.3 事件流图
 > mermaid：事件→指令级联链（覆盖 saga/process manager 跨聚合长流程一致性）
 
@@ -72,6 +102,8 @@ flowchart LR
 |--------|-------------|-------------------|
 | order-summary-view | OrderPlaced, PaymentCaptured | 异步 |
 
+> 跨聚合最终一致的 **Saga 补偿矩阵 + Projection 重建策略 + 幂等键** 模板见 `references/ddd-evented-playbook.md`（O5，设计层 ONLY 不生成代码）。
+
 > 显式声明：事件用于**变更通知与投影驱动，不引入事件溯源持久化**。事件命名规范 `OrderPlaced`（名词+过去式动词），全系统一致。
 
 ## 4 聚合状态迁移                  <a id="state-machines"></a>
@@ -85,7 +117,7 @@ flowchart LR
 | 创建 | PlaceOrder | order | 已支付 | 总金额>0 |
 | 已支付 | Ship | order | 已发货 | 已收款 |
 
-> 区分**聚合状态机**（本表，聚合事务边界内）与**跨聚合流程状态机**（入 saga，不在聚合状态机内表达）。
+> 区分**聚合状态机**（本表，聚合事务边界内）与**跨聚合流程状态机**（入 saga，不在聚合状态机内表达）——saga 补偿矩阵模板见 `references/ddd-evented-playbook.md`（O5）。
 
 ## 5 数据模型 / ER（概念级）         <a id="erd"></a>
 

package/skills/architecture-design/references/s3.5-loading-protocol.md

@@ -16,7 +16,8 @@
 1. **先索引、后按域**：子代理先读 ① 索引层做路由（识别 change 触及哪些 BC），再按需加载 ② 该域的详细页。
 2. **单域单次**：跨多域时一次只装载一个域文件，逐域分步处理（与 ch06 增量 SOP 对齐）。
 3. **引用非复制**：只读不改；产品级聚合注册表是唯一事实源，change 内设计**引用**注册表 id，不重定义。
-4. **迭代状态判定**（P1）：读快照还是读全局由迭代状态决定——
+4. **业务语言 grounding（O2）**：变更级设计加载触及 BC 的业务术语时，读快照 §0 索引定位 → 跳转 `docs/architecture/CONCEPTS.md` 取定义（**唯一内容写入点**，根位置自 v0.23.0 已弃用；§0 只路由不装载定义）。本项计入 ~2K 预算（§0 ~150 token + 按需读 CONCEPTS.md 相关节），**人审把关**。
+5. **迭代状态判定**（P1）：读快照还是读全局由迭代状态决定——
    - 迭代中（`snapshot_status: in-flight`）→ 读 `iterations/vN/` 快照（产品级决策权威）
    - 迭代收尾（`snapshot_status: superseded/archived`）→ 读全局当前态（唯一权威）
 
@@ -28,10 +29,10 @@
 2. 触及域按"受影响优先级"逐域分步处理（每步 ≤1 域）。
 3. 加载前做 token 估算，超预算 → 告警 + 降级，而非硬约束失败。
 
-## token 预算自动化校验
+## token 预算校验（人审项）
 
-- 锚点（§1-2）与域页 token 预算加**自动化校验**（镜像 frontmatter-lint 模式，进 npm test）——不靠 LLM 自律。
-- S3.5 产物自检 + S4 审计抽查：`iterations/vN/architecture.md` 的 §1-2 必须一句话级；`domains/<bc>.md` 单文件 ≤1500 token（超出继续拆子页）。
+- 锚点（§1-2）、§0 统一语言索引与域页 token 预算均为**人审自查项**（S3.5 产物自检 + S4 审计抽查），**无机械门禁**——本节原写「进 `npm test`」（自动化校验表述）属悬空规范，已于 2026-09-25 按设计方案 §2.6 处置 (b) 改写（补齐机械校验的路线见该方案 CQ-9，可行性已上调，留待独立批次）。
+- 具体口径：`iterations/vN/architecture.md` 的 §0 ≤ ~150 token、§1-2 必须一句话级；`domains/<bc>.md` 单文件 ≤1500 token（超出继续拆子页）。
 
 ## 与既有加载协议的关系
 

package/skills/architecture-design/references/s3.5-product-architecture.md

@@ -20,7 +20,7 @@
 | 步 | 动作 | 方法论 | 产出 |
 |----|------|--------|------|
 | 0 | 输入梳理 | 读 PRD 功能清单 + plan 技术方向 + prototype + CONCEPTS + 现有基线 | 功能域→候选业务能力映射 |
-| 1 | 限界上下文识别 | 功能域分组 + 词汇聚类 + 活动对象矩阵（ch04，重叠>70% 合并） | Context Map：BC 表 + 关系图（6 关系类型）+ 语言边界术语表 |
+| 1 | 子域与限界上下文识别 | 子域分类 Core/Supporting/Generic（ch04，问题空间先行，不列实现载体）+ 功能域分组 + 词汇聚类 + 活动对象矩阵（重叠>70% 合并） | §1.1 子域地图（问题空间·投资分级）+ Context Map：BC 表 + 关系图（6 关系类型）+ 语言边界术语表 + **§0 统一语言索引**（per-BC，术语→CONCEPTS.md 锚点，**不含定义**） |
 | 2 | 聚合识别 | 聚合四要素（ch04）+ 活动对象矩阵 | 聚合注册表（唯一事实源） |
 | 3 | 指令与事件识别 | CQRS 指令分流（ch05：Command/Read/Query + 阻断测试）+ 事件三类 | 指令表 + 事件表 + 事件流图 + 读模型投影清单 |
 | 4 | 聚合状态迁移 | 聚合根=状态机守卫（Vernon） | stateDiagram + 状态表（含触发源上下文、guard 不变量） |
@@ -33,7 +33,7 @@
 
 **按域详细页产出（v0.36.3，domains/ 生产者）**：Step 1 识别 BC 后、Step 2-6 每个触及域细化时，同步产出 `domains/<bc>.md`（职责/聚合明细/指令事件/状态迁移/ER 局部/时序/对外契约）与 `diagrams/`（erd/sequences）——它们是按域分段加载（`s3.5-loading-protocol.md` 第②段）与 reviewer product A1 的审查对象；单文件 ≤1500 token。
 
-**模板**：按 `references/s3.5-architecture-template.md` 骨架产出（6 产物 + 厚锚点 + marker + provenance）。
+**模板**：按 `references/s3.5-architecture-template.md` 骨架产出（6 产物 + **§0 统一语言索引** + **§1 子域/BC 拆分** + 厚锚点 + marker + provenance；§0/§1.1 的日期锚门控见该模板注释）。
 
 ## 产品级评审门（Step 8）
 
@@ -41,7 +41,7 @@
 
 | 维度 | 校验 |
 |------|------|
-| A1 | 结构完备（6 产物章节存在 + marker/锚点可解析，机械预检） |
+| A1 | 结构完备（6 产物章节 + §0 统一语言索引 per-BC·无定义列 + §1.1 子域段与 §1.2 物理分离·含三分类·业务问题列非空·**反例：不含 service/包名类实现载体词** + marker/锚点可解析，机械预检；存量 `established_at` < 2026-09-25 **或日期缺失/不可解析** → WARN 不 FAIL） |
 | A2 | SQL/结构有效（机械 grep，若含 sql/） |
 | A3 | 跨域一致性（AA↔IA 双对齐，F2 门禁） |
 | A4 | 与 PRD 功能清单覆盖映射（F001_P0 逐条 → BC/聚合/API） |
@@ -49,7 +49,7 @@
 | A6 | conventions 合规 |
 
 规则：≤3 轮修复循环 + 收敛检测（连续两轮不一致项不缩小 → 转人工）；PASS 才进 S3（2026-08-19：ARCH 上移 S3 前，原"进 S4"）。
-**skip 时**：architecture-reviewer 不执行，但 skip 必须物化（iterations/vN/SKIPPED 标记 + 理由）。
+**skip 时**：architecture-reviewer 不执行，但 skip 必须物化（**统一命名 `iterations/vN/SKIPPED.md`**——审计 B8：存量有 `SKIPPED` 与 `SKIPPED.md` 两种形态，自本规范起一律带 `.md`；最小内容三段 = 迭代 / 判定（日期+判定者）/ 理由，详式可加覆盖判断与衔接）。
 
 ### 复利捕获（Step 9，v0.36.3 复利链路修复）
 
@@ -83,7 +83,7 @@ ARCH 完成（评审 PASS 或 skip 已物化）后，**阻塞确认**（AskUserQ
 
 ## 完成条件
 
-- `docs/architecture/iterations/vN/architecture.md` 已产出（6 产物，provenance 标注）
+- `docs/architecture/iterations/vN/architecture.md` 已产出（6 产物 + §0/§1.1 结构增强，provenance 标注）
 - 产品级评审门 verdict = PASS（或 skip 已物化）
 - orchestrator.yaml 中 ARCH 阶段状态 = completed（workflow_phase: architecture）
 - **未触发** arch-merge 全局覆盖写（预测态不进实际态，P1）
@@ -92,6 +92,6 @@ ARCH 完成（评审 PASS 或 skip 已物化）后，**阻塞确认**（AskUserQ
 ## 常见陷阱
 
 - **过度详设**：契约级（每 API schema/每表全字段）留给 change 落地涌现，产品级只做结构级（P4）。
-- **skip 不物化**：跳过必须写 iterations/vN/SKIPPED + 理由，否则 S4 arch-readiness 卡死 hotfix 通道（v0.32.2 C1 死锁链同类）。
+- **skip 不物化**：跳过必须写 `iterations/vN/SKIPPED.md`（命名统一见上，B8）+ 理由，否则 S4 arch-readiness 卡死 hotfix 通道（v0.32.2 C1 死锁链同类）。
 - **事件只识别不投影**：引入事件必须补"读模型投影清单"（§3.4），否则读模型更新无定义。
 - **ER 先行**：先画 ER 再定聚合 = 数据库驱动设计，违背 DDD（顺序纪律）。

package/skills/architecture-design/templates/architecture.md

@@ -2,9 +2,19 @@
 change_id: <change-name>
 date: YYYY-MM-DD
 arch_design_decision: required | skipped
+mode: inline | sdd                    # O9 必填：执行形态
+provenance: forward-designed | reverse-engineered | mixed   # O9 必填：来源性质
+as_is_anchor: <version@章节锚点 或 none>                     # O9 必填：As-Is 冻结锚（§1 复制源）
+iteration_version: <vN 或 none>        # O9 必填：所属产品级迭代
+product_snapshot: <docs/architecture/iterations/vN/architecture.md 或 none>  # O9 必填
 ---
 # Architecture 增量设计: <change-name>
 
+> **O9 可读性纪律（设计意图前置 · 证据下沉）**：
+> ① **首屏 = 设计意图**——本文件开头（H1 后）先用 ≤10 行说清「为什么改、改什么、关键取舍」，人读不懂即不合格；
+> ② **`file:line` 级举证与 ADR-lite 正文下沉**到各节末尾「证据」小字或 `evidence/` 子目录，**不得淹没设计意图**（emp-auth 实测 126KB/30+ 处 file:line 的法医化膨胀是反例）；
+> ③ 证据可下沉**不可删除**（判据完整性不削弱）；frontmatter 5 项必填（缺项 → 评审 WARN，存量按日期锚门控不追溯）。
+
 ## 1. As-Is 基线（冻结复制）
 
 > 从全局 ARCHITECTURE.md 复制当前相关 BC/聚合/Context Map 到此处。
@@ -46,6 +56,16 @@ arch_design_decision: required | skipped
 | 聚合 | 操作类型 | 命令/查询 | 事务边界 | 说明 |
 |------|---------|---------|---------|------|
 
+### 2.5 领域事件变更（O4 · 事件化场景必填版本字段，缺失 → 评审阻塞）
+
+| 事件 | 操作(new/extend/retire) | 源聚合 | schema 版本 | 兼容级别(major/minor) | 携带数据变更 | 消费方 |
+|------|------------------------|--------|------------|----------------------|------------|--------|
+| OrderPlaced | extend | order:Order | 1.2.0 | minor | +shippingAddress(可选) | payment, stock |
+
+> 版本策略 / upcasting / tombstone 纪律见产品级快照 §3.2 的「事件 schema 版本策略门禁」段；
+> retire 须带 reason；事件经 `.arch-delta.json`（kind=event，`fields.owner_aggregate` 挂宿主）登记。
+> **无事件增量时本节留空即可**（勿删节——O9 结构完整性依赖章节存在）。
+
 ## 3. 变更分叉级联分析
 
 ### 3.1 直接依赖

package/skills/ce-compound/references/concepts-vocabulary.md

@@ -1,6 +1,6 @@
 # CONCEPTS.md vocabulary rules
 
-`CONCEPTS.md` defines the words that mean something specific in this codebase — substrate that `docs/solutions/` and AGENTS.md can cite without redefinition. Lives at the repo root. Terms enter two ways — accretion and seeding (below) — and the file is created the first time either path produces a qualifying entry.
+`CONCEPTS.md` defines the words that mean something specific in this codebase — substrate that `docs/solutions/` and AGENTS.md can cite without redefinition. Lives at `docs/architecture/CONCEPTS.md` (the repo-root location was retired in v0.23.0; if a root file exists, migrate it). Terms enter two ways — accretion and seeding (below) — and the file is created the first time either path produces a qualifying entry.
 
 ## How terms enter: accretion and seeding
 

package/skills/ce-compound/references/full-mode-workflow.md

@@ -262,7 +262,7 @@ When creating a new doc, preserve the section order from `assets/resolution-temp
 
 **First, read `references/concepts-vocabulary.md`.** This is unconditional. Do not pre-judge from memory that nothing qualifies — the reference's criteria are non-obvious and qualifying terms often live in the surrounding conversation rather than the new doc itself. Reading the reference is what makes the rest of the phase possible.
 
-Then, applying those criteria, scan the new doc **and** the surrounding conversation for qualifying domain terms. If `CONCEPTS.md` exists at repo root, add missing qualifying terms and refine existing entries when new precision surfaced. If it does not exist and at least one qualifying term surfaced, create it.
+Then, applying those criteria, scan the new doc **and** the surrounding conversation for qualifying domain terms. If `docs/architecture/CONCEPTS.md` exists (repo-root location retired in v0.23.0), add missing qualifying terms and refine existing entries when new precision surfaced. If it does not exist and at least one qualifying term surfaced, create it at `docs/architecture/CONCEPTS.md`.
 
 **Verify behavior assertions against source before writing them.** When an entry asserts how code behaves (states, transitions, limits, semantics), Read the defining source at the current tree first — an entry drafted from a session-level summary is exactly how wrong semantics enter the glossary. Phase 2.45 re-checks these entries, but the cheap fix is to not write the error.
 
@@ -384,7 +384,7 @@ After the learning is written and the refresh decision is made, check whether th
       ```
    c. In full interactive mode, explain to the user why this matters — agents working in this repo (including fresh sessions, other tools, or collaborators without the plugin) won't know to check `docs/solutions/` unless the instruction file surfaces it. Show the proposed change and where it would go, then use the platform's blocking question tool to get consent before making the edit: `AskUserQuestion` in Claude Code (call `ToolSearch` with `select:AskUserQuestion` first if its schema isn't loaded), `request_user_input` in Codex, `ask_question` in Antigravity CLI (`agy`), `ask_user` in Pi (requires the `pi-ask-user` extension). Fall back to presenting the proposal in chat only when no blocking tool exists in the harness or the call errors (e.g., Codex edit modes) — not because a schema load is required. Never silently skip the question. In lightweight mode (interactive or headless), output a one-liner note and move on. In full headless mode, **do not edit instruction files** — surface the gap in the terminal report as `Instruction-file edit: gap noted, not applied` (headless scope is documentation capture, not project-config edits; a human-invoked interactive run applies the edit with consent)
 
-5. **If `CONCEPTS.md` exists at repo root, run a parallel discoverability check for it.** Assess whether the instruction file would lead an agent to discover the project's shared domain vocabulary. Use the same workflow as the `docs/solutions/` check above: same target file, same edit-placement judgment, same consent-then-edit interaction shape per mode. A line in an existing section is almost always better than a new headed section. Example calibration when nothing else fits:
+5. **If `docs/architecture/CONCEPTS.md` exists (repo-root location retired in v0.23.0), run a parallel discoverability check for it.** Assess whether the instruction file would lead an agent to discover the project's shared domain vocabulary. Use the same workflow as the `docs/solutions/` check above: same target file, same edit-placement judgment, same consent-then-edit interaction shape per mode. A line in an existing section is almost always better than a new headed section. Example calibration when nothing else fits:
 
    ```
    CONCEPTS.md  # shared domain vocabulary (entities, named processes, status concepts) — relevant when orienting to the codebase or discussing domain concepts

package/skills/ce-compound/references/lightweight-mode.md

@@ -16,7 +16,7 @@ The orchestrator (main conversation) performs ALL of the following in one sequen
    - YAML frontmatter with track-appropriate fields, applying the YAML-safety quoting rule for array items (see `references/yaml-schema.md` > YAML Safety Rules)
    - Bug track: Problem, root cause, solution with key code snippets, one prevention tip
    - Knowledge track: Context, guidance with key examples, one applicability note
-4. **Vocabulary capture (update-only)**: if `CONCEPTS.md` exists at repo root, read `references/concepts-vocabulary.md`, then scan the new doc and the conversation for qualifying terms and add/refine entries silently (same criteria as Phase 2.4). Do **not** bootstrap or seed in lightweight mode — if `CONCEPTS.md` does not exist, defer creation to a Full run, which owns seeding. Record the outcome in the output (e.g., "Vocabulary: 1 entry refined" or "scanned, no qualifying terms"). If you refined `CONCEPTS.md` and the project's active instructions and conventions already in your context do not surface it, add the discoverability tip to the output below — lightweight **tips**, it does not edit instruction files (an interactive Full run owns that edit after consent; headless Full also tips/reports only).
+4. **Vocabulary capture (update-only)**: if `docs/architecture/CONCEPTS.md` exists (repo-root location retired in v0.23.0 — root-only probe misses bootstrapped projects), read `references/concepts-vocabulary.md`, then scan the new doc and the conversation for qualifying terms and add/refine entries silently (same criteria as Phase 2.4). Do **not** bootstrap or seed in lightweight mode — if `CONCEPTS.md` does not exist, defer creation to a Full run, which owns seeding. Record the outcome in the output (e.g., "Vocabulary: 1 entry refined" or "scanned, no qualifying terms"). If you refined `CONCEPTS.md` and the project's active instructions and conventions already in your context do not surface it, add the discoverability tip to the output below — lightweight **tips**, it does not edit instruction files (an interactive Full run owns that edit after consent; headless Full also tips/reports only).
 5. **Read-only discoverability check**: Using the project's active instructions and conventions already in your context, assess whether they surface `docs/solutions/` against the three criteria under **Discoverability Check** in `references/full-mode-workflow.md`. Do not open, offer to edit, or edit instruction files; Lightweight only reports the result. Record one of:
    - `no gap` when active project instructions surface the knowledge store
    - `gap noted — instruction-file tip emitted` when active project instructions exist but do not surface it