soloforge 1.1.46 → 1.1.48

package/templates/build/enforced.md

@@ -5,6 +5,8 @@ gate: build-gate
 title: build阶段强制检查清单
 sync_policy: engine_only
 status: active
+extra:
+  owner_mechanism: mc-stage-gate-engine
 checks:
   - id: TS-Q01
     executor: regex_pattern_scan
@@ -109,7 +111,7 @@ checks:
   - id: SEC-07
     executor: regex_pattern_scan
     rule: "禁止 ../ 路径遍历风险"
-    severity: error
+    severity: warning
     check_type: deterministic
     pattern: '/\.\.[\\\/]/'
     languages: [通用]
@@ -161,11 +163,235 @@ checks:
     rule: "JWT 必须校验签名算法，禁止未校验直接 decode"
     severity: error
     check_type: deterministic
-    pattern: '/\bjwt\.decode\s*\(/'
+    pattern: '/\bjwt\.decode\s*\(/i'
     languages: [通用]
     evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无未校验 JWT 命中）"]
     gate: build-gate
     target: "self"
+  # —— 日志契约（LOG-ZH，regex 验证中文日志；原 BLD-G03 中文日志部分硬化）——
+  - id: LOG-ZH
+    executor: regex_pattern_scan
+    rule: "业务日志须含中文事件名（方便调试观察）；命中=日志字符串无中文字符（纯英文/符号）"
+    severity: warning
+    check_type: deterministic
+    pattern: '/(console\.(log|info|warn|error)|logger?\.\w+)\s*\(\s*["''][^"''一-龥]*["'']/'
+    languages: [通用]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无纯英文日志命中）"]
+    gate: build-gate
+    target: "self"
+  # —— 代码架构检查（从 design-gate 迁入，代码实现阶段归属）——
+  - id: ARC-02
+    executor: regex_pattern_scan
+    rule: "禁止 Entity 直接暴露给外部接口，必须用 DTO"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bpublic\s+\w*Entity\b\s+\w+\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Entity 直接暴露命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-03
+    executor: regex_pattern_scan
+    rule: "写操作（save/create/update/delete）必须有 @Transactional"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\.(save|insert|update|delete|remove|create)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无写操作缺事务命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-04
+    executor: regex_pattern_scan
+    rule: "禁止直接 new Service/Repository/Mapper/Manager，必须依赖注入"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bnew\s+\w*(Service|Repository|Repo|Dao|Mapper|Manager)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无直接 new 服务对象命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-06
+    executor: regex_pattern_scan
+    rule: "前端 API 调用必须封装到 service 层，禁止组件内直接 fetch/axios"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\b(fetch|axios)\s*\(/'
+    languages: [ts]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无组件直接 API 调用命中）"]
+    gate: build-gate
+    target: "self"
+  - id: ARC-08
+    executor: regex_pattern_scan
+    rule: "Service 层禁止直接操作 HttpServletRequest/Response"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bHttpServletRequest\b|\bHttpServletResponse\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Service 操作 HttpServlet 命中）"]
+    gate: build-gate
+    target: "self"
+  # —— 并发安全（CON-*，从 verify/enforced.md 物理归位；gate 本就是 build-gate）——
+  - id: CON-01
+    executor: regex_pattern_scan
+    rule: "共享可变状态必须有并发保护"
+    severity: error
+    check_type: deterministic
+    pattern: '/\b(public|private|protected)\s+static\s+[\w<>,\s]*\b(HashMap|ArrayList|HashSet|LinkedList)\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无未保护共享状态命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-02
+    executor: regex_pattern_scan
+    rule: "分布式环境禁止使用 JVM 级锁"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\bsynchronized\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 JVM 级锁误用命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-03
+    executor: regex_pattern_scan
+    rule: "先查后改（如库存/计数）必须用原子操作"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\.(findById|getById|getOne|selectById)\s*\([^)]*\)/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无非原子先查后改命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-04
+    executor: regex_pattern_scan
+    rule: "禁止 @Transactional 同类内部调用导致事务失效"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\bthis\.\w+\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无事务自调用命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-05
+    executor: regex_pattern_scan
+    rule: "事务内禁止执行外部调用（HTTP/RPC）"
+    severity: warning
+    check_type: deterministic
+    pattern: '/\.(getForObject|postForObject|exchange|execute)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无事务内外部调用命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-06
+    executor: regex_pattern_scan
+    rule: "SimpleDateFormat 非线程安全，禁止作为共享成员"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bstatic\s+[\w<>,\s]*SimpleDateFormat\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 SimpleDateFormat 共享命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-07
+    executor: regex_pattern_scan
+    rule: "ThreadLocal 必须清理避免内存泄漏"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bnew\s+ThreadLocal\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 ThreadLocal 未清理命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-08
+    executor: regex_pattern_scan
+    rule: "HashMap/ArrayList 等禁止作为共享可变类成员"
+    severity: error
+    check_type: deterministic
+    pattern: '/\b(private|protected|public)\s+(?!static)[\w<>,\s]*\b(HashMap|ArrayList|HashSet|LinkedList)\s*[=;]/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无非线程安全集合成员命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-09
+    executor: regex_pattern_scan
+    rule: "CompletableFuture 链必须处理异常"
+    severity: error
+    check_type: deterministic
+    pattern: '/\.(runAsync|supplyAsync)\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无未处理异常命中）"]
+    gate: build-gate
+    target: "self"
+  - id: CON-10
+    executor: regex_pattern_scan
+    rule: "线程池必须正确配置拒绝策略"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bnew\s+ThreadPoolExecutor\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无未配置拒绝策略命中）"]
+    gate: build-gate
+    target: "self"
+  # —— API 规范（API-03~10，从 verify/enforced.md 归位；API-01/02 与 ARC-02/03 重复已删）——
+  - id: API-03
+    executor: regex_pattern_scan
+    rule: "接口必须有权限注解"
+    severity: error
+    check_type: deterministic
+    pattern: '/@(Get|Post|Put|Delete|Request)Mapping\s*\(/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无接口缺权限注解命中）"]
+    gate: build-gate
+    target: "self"
+  - id: API-04
+    executor: regex_pattern_scan
+    rule: "禁止硬编码分页参数，必须参数化"
+    severity: error
+    check_type: deterministic
+    pattern: '/\b(pageNum|pageSize)\s*=\s*\d/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无硬编码分页命中）"]
+    gate: build-gate
+    target: "self"
+  - id: API-06
+    executor: regex_pattern_scan
+    rule: "接口路径须符合 RESTful 规范"
+    severity: warning
+    check_type: deterministic
+    pattern: '/@(Get|Post|Put|Delete)Mapping\s*\(\s*[^\)]*(get|list|create|delete|update)/i'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无路径违规命中）"]
+    gate: build-gate
+    target: "self"
+  - id: API-07
+    executor: regex_pattern_scan
+    rule: "接口必须使用统一响应包装（ApiResult/Result/R）"
+    severity: error
+    check_type: deterministic
+    pattern: '/\bResponseEntity\s*<\s*\w*Entity\b/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无裸返回命中）"]
+    gate: build-gate
+    target: "self"
+  - id: API-08
+    executor: regex_pattern_scan
+    rule: "分页接口必须返回标准分页结构"
+    severity: error
+    check_type: deterministic
+    pattern: '/\.(findAll|listAll)\s*\(\s*\d/'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无非标准分页命中）"]
+    gate: build-gate
+    target: "self"
+  - id: API-09
+    executor: regex_pattern_scan
+    rule: "接口路径须含版本号"
+    severity: error
+    check_type: deterministic
+    pattern: '/@(Get|Post|Put|Delete|Request)Mapping\s*\(\s*"\/(?!api\/v\d)/i'
+    languages: [java]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无缺版本号命中）"]
+    gate: build-gate
+    target: "self"
   - id: BLD-G01
     executor: upstream_gate_check
     rule: "design-gate 已通过，所有前置设计产物完备"
@@ -182,14 +408,6 @@ checks:
     evidence_required: ["lazy_pattern_detector 输出（hard_fail=0）","空函数体扫描结果（0 匹配）","空 catch 扫描结果（0 匹配）"]
     gate: build-gate
     target: "self"
-  - id: BLD-G03
-    executor: lazy_pattern_check
-    rule: "变更代码必须满足中文注释与日志契约：后端类/方法有中文 Javadoc，关键业务行有中文行注释，业务日志使用中文事件名"
-    severity: error
-    check_type: deterministic
-    evidence_required: ["non_chinese_comment 检测结果（须为 0）","non_chinese_log 检测结果（须为 0）"]
-    gate: build-gate
-    target: "self"
   - id: BLD-G04
     executor: tsc_compile
     rule: "tsc --noEmit 零错误，项目构建成功"
@@ -200,46 +418,88 @@ checks:
     target: "self"
   - id: BLD-G05
     executor: vitest_run
-    rule: "全量测试通过，无失败用例；增量代码行覆盖率>=80%"
+    rule: "全量测试通过，无失败用例（vitest_run 验测试通过；覆盖率阈值非本 check 确定性覆盖，归人工/CI 把关——coverage_threshold executor 注册但未接入 build-gate）"
     severity: error
     check_type: deterministic
-    evidence_required: ["测试报告（passed/failed/total）","覆盖率报告（增量行覆盖率数值）"]
+    evidence_required: ["测试报告（passed/failed/total）"]
     gate: build-gate
     target: "self"
-  - id: BLD-G06
-    executor: lazy_pattern_check
-    rule: "无硬编码密钥、无未鉴权写接口、无 SQL 注入风险、依赖无高危漏洞"
+  # —— 超大系统 build 前研讨兜底（BLD-DELIB：开发切片计划 SLC 切片数>=5 时须有 build 研讨记录，补下限防 AI 跳过研讨；切片计划不存在或<5 跳过）——
+  - id: BLD-DELIB
+    executor: slice_deliberation_gate
+    rule: "超大系统（开发切片计划 SLC 切片数>=5）build 写代码前须 deliberate 研讨实现策略（研讨记录 docs/研讨记录/构建/产物-研讨记录.md 存在）；切片计划不存在或切片<5 则跳过"
+    severity: error
+    check_type: deterministic
+    evidence_required: ["docs/architecture/02-开发切片计划.md"]
+    gate: build-gate
+    target: "self"
+  # —— db/api 适用性兜底（③ build 兜底：design_doc 声明「适用」须产出，防 design 漏产致 build 缺地基）——
+  - id: BLD-DBAPI
+    executor: applicability_check
+    rule: "build 前置兜底（通用 check，所有 build verify 跑）：design_doc「产物适用性声明」声明「适用」的 database_design/api_specification 须已产出（design_doc 不存在则跳过，兼容小改跳 design）"
     severity: error
     check_type: deterministic
-    evidence_required: ["硬编码密钥扫描结果（须为 0）","未鉴权写接口扫描结果（须为 0）","注入防护方案确认","依赖漏洞扫描报告（高危/严重须为 0）"]
+    evidence_required: ["数据库设计文档模版", "API接口规格文档模版"]
+    gate: build-gate
+    target: "self"
+  # —— 多工程结构兜底（MULTI-ENGINE-STRUCT：intent projects 每端须有 src/ + 独立 .gitignore）——
+  - id: MULTI-ENGINE-STRUCT
+    executor: multi_engine_structure_check
+    rule: "多工程项目（intent projects 声明）每端工程须有 src/ + 独立 .gitignore（首个切片建工程骨架）；单工程跳过"
+    severity: error
+    check_type: deterministic
+    evidence_required: ["intent.yaml projects"]
+    gate: build-gate
+    target: "self"
+  # —— 测试计划结构（TESTPLAN-STRUCT，test_plan 产物结构完整性）——
+  - id: TESTPLAN-STRUCT
+    executor: document_structure
+    rule: "测试计划须含「测试范围」「测试条目」「环境与数据」「执行顺序」「验收标准」「完成判定」章节"
+    severity: warning
+    check_type: deterministic
+    required_artifact: 测试计划模版
+    evidence_required: ["docs/build/测试计划.md"]
+    gate: build-gate
+    target: self
+  # —— 产物间一致性（cross_validation：测试覆盖需求）——
+  - id: XVAL-TEST-REQ
+    executor: cross_validation
+    rule: "REQ-* 一致性+覆盖率"
+    severity: warning
+    check_type: deterministic
+    required_artifact: 测试计划模版
+    evidence_required: ["需求分析模版"]
+    gate: build-gate
+    target: "self"
+  - id: TESTPLAN-BLOCK
+    executor: document_structure
+    check_type: deterministic
+    severity: error
     gate: build-gate
+    required_artifact: 测试计划模版
+    rule: "测试条目章节须有表格行（反退化：禁只列前几行后省略/一句话概括代替）"
+    block_check:
+      item_pattern: '^##\s+2\.'
+      require_table: true
+      min_table_rows: 2
+    evidence_required: ["测试计划模版"]
     target: "self"
 ---
 
 # build-gate 强制检查清单
 
-22 条确定性检查。bridge 从此文件聚合。
+48 条确定性检查（3 agent 交叉验证修复：8 过宽 regex error→warning / 删 4 形同虚设 / 加 TESTPLAN-STRUCT / SEC-12 加 Java JWT / 加 BLD-DELIB 超大系统研讨兜底 / 加 MULTI-ENGINE-STRUCT 多工程骨架兜底）。注：verify 域 ARCH-DEP（external_command 缺 command → dependency-cruiser 从未真跑、永远 fail-closed）与 ARC-05（幽灵 check：注释/guidance 引用但 enforced checks 不存在）为假覆盖，待 verify 域修（详见 verify/enforced.md）。
 
 对应工程经验：
-- TS-Q01
-- TS-Q02
-- TS-Q03
-- TS-Q04
-- SEC-01
-- SEC-02
-- SEC-03
-- SEC-04
-- SEC-05
-- SEC-06
-- SEC-07
-- SEC-08
-- SEC-09
-- SEC-10
-- SEC-11
-- SEC-12
-- BLD-G01
-- BLD-G02
-- BLD-G03
-- BLD-G04
-- BLD-G05
-- BLD-G06
+- TS-Q01~04（TS 类型/相等/var）
+- SEC-01~12（安全：注入/密钥/日志/重定向/路径/反序列化/SSRF/CORS/Cookie/JWT）
+- ARC-01~08（架构：Controller/Entity/事务/DI/前端fetch/循环依赖/HttpServlet）
+- CON-01~10（并发：共享状态/JVM锁/原子/事务自调用/ThreadLocal/线程池）—— 归位自 verify
+- API-03~10（API：权限/分页/校验/RESTful/响应包装/版本号/Swagger）—— 归位自 verify
+- BLD-G01/02/04/05（前置门禁/偷懒模式/tsc/vitest）
+- BLD-DELIB（超大系统 build 前强制研讨实现策略：SLC≥5 须有 build 研讨记录）
+- MULTI-ENGINE-STRUCT（多工程骨架兜底：intent projects 每端须有 src/ + 独立 .gitignore）
+- LOG-ZH（中文日志 regex 验证；原 BLD-G03 中文日志部分硬化）
+- 中文注释纪律 → guidance《注释纪律》（软，原 BLD-G03 non_chinese_comment 拆出）
+- 原 BLD-G06（密钥/鉴权/注入/漏洞）已删：密钥由 SEC-04、注入由 SEC-01、漏洞由依赖扫描覆盖（重复+假声明）
+- XVAL-TEST-REQ（测试↔需求覆盖）

package/templates/build//344/270/223/351/241/271/345/256/236/347/216/260.md

@@ -0,0 +1,75 @@
+---
+id: ka-guidance-专项实现
+kind: guidance
+title: 专项实现
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 数据库迁移
+  - 接口集成
+  - 性能优化
+  - 性能分析
+  - 异步
+  - 缓存
+  - 定时任务
+  - 文件上传
+extra:
+  name: specialized-implementation
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: build
+  domain: build
+  owner_mechanism: mc-backend-pattern
+---
+
+# 专项实现：特定场景怎么做
+
+> 吸收旧的「数据库迁移」「接口集成流水线」「性能分析」「性能流水线」「缓存策略」「异步导出」等。
+> 按需注入，不强制全套。
+
+## 数据库迁移
+
+- migration 脚本成对（up + down），可回滚
+- 大表变更评估锁表影响，分批/在线 DDL
+- 数据迁移新老比对，回滚后一致性验证
+- 详见 [[兼容性与迁移评估]]
+
+## 接口集成
+
+- 接口契约先行（OpenAPI），契约评审后再实现
+- 字段映射精确到 表.字段
+- 对接外部系统考虑超时/重试/幂等/签名
+- 异常路径明确（对方不可用怎么办）
+
+## 性能优化
+
+- 先测量后优化（性能分析数据为证据，不靠猜）
+- 优化目标量化（如 P99 < 200ms）
+- 关注 N+1 查询、大循环、不必要序列化
+- 缓存考虑一致性/失效/穿透/雪崩
+
+## 异步与定时
+
+- 异步任务幂等（可重试不重复执行）
+- 定时任务考虑并发执行/分布式锁
+- 长任务可中断、可观测进度
+
+## 文件上传/导出
+
+- 限制类型/大小，校验内容（防恶意文件）
+- 大文件流式处理/分片，不一次性进内存
+- 导出异步化，提供进度查询
+
+## 禁止
+
+- 迁移脚本无回滚（违规）
+- 接口集成不定义契约（违规）
+- 性能优化无测量证据（违规，[[证据驱动与反幻觉]]）
+- 异步任务不幂等（违规）

package/templates/build//345/256/211/345/205/250/345/212/240/345/233/272.md

@@ -0,0 +1,75 @@
+---
+id: ka-guidance-安全加固
+kind: guidance
+title: 安全加固
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 安全
+  - 权限
+  - 认证
+  - 授权
+  - 加固
+  - 鉴权
+  - 熔断
+  - 限流
+extra:
+  name: security-hardening
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: build
+  domain: build
+  owner_mechanism: mc-privacy-boundary
+---
+
+# 安全加固：编码时怎么堵漏洞
+
+> 吸收旧的「安全加固」「安全审查」「安全审计」「权限认证」「熔断降级」。
+> build-gate 的 SEC-01~12 是硬门禁（确定性正则），本 guidance 是方法指导。
+
+## 输入校验（第一道防线）
+
+- 所有外部输入校验：类型、范围、格式、长度
+- SQL 用参数化查询，禁字符串拼接（SEC-01）
+- 禁 innerHTML 直接赋值，用安全 DOM API/转义（SEC-02，防 XSS）
+- 禁 eval/Function 动态执行（SEC-03）
+
+## 认证与授权
+
+- 每个接口明确权限要求
+- 写操作必须鉴权
+- JWT 校验签名算法，禁未校验 decode（SEC-12）
+- Cookie 设 secure/httpOnly（SEC-11）
+
+## 敏感信息
+
+- 密钥走环境变量/密钥管理，禁硬编码（SEC-04，shared-gate SEC-02）
+- 日志禁打印密码/token/身份证（SEC-05）
+- 路径参数防遍历（SEC-07）
+
+## 外部交互
+
+- 重定向校验目标（SEC-06，防开放重定向）
+- 外部请求校验目标（SEC-09，防 SSRF）
+- 反序列化白名单（SEC-08）
+- CORS 收紧 allowedOrigins，禁 `*`（SEC-10）
+
+## 稳定性（熔断降级）
+
+- 跨系统调用设超时/重试/熔断
+- 限流保护核心接口
+- 降级策略：依赖不可用时系统的行为
+
+## 禁止
+
+- 信任客户端输入不校验（违规）
+- 拼接 SQL（违规）
+- 打印敏感信息到日志（违规）
+- 写接口不鉴权（违规）

package/templates/build//346/263/250/351/207/212/347/272/252/345/276/213.md

@@ -0,0 +1,48 @@
+---
+id: ka-guidance-注释纪律
+kind: guidance
+title: 注释纪律
+sync_policy: engine_only
+status: active
+triggers:
+  - 写代码
+  - 实现
+  - 编码
+  - 加类
+  - 加方法
+  - 注释
+  - Javadoc
+  - 文档注释
+extra:
+  name: comment-discipline
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  domain: build
+  owner_mechanism: mc-backend-pattern
+---
+
+# 注释纪律
+
+> 代码注释中文契约（原 BLD-G03 的 `non_chinese_comment` 部分）。
+> 为何软：判"类有无 doc""doc 是否含职责边界"需 AST + 语义，regex_pattern_scan（行扫）做不到精确。硬标会假覆盖（=原 BLD-G03 的坑）。靠 guidance 注入 + AI 自觉 + 对抗审查复核。中文**日志**由硬规则 LOG-ZH 验证（regex 可判）。
+
+## 类必须有中文 doc
+- 说明**职责 + 边界**：这个类管什么、不管什么、与谁协作
+
+## 方法必须有中文 doc
+- **职责**（做什么）+ **边界**（不做什么）+ **入参**（含义/约束）+ **出参**（含义）+ **异常**（何时抛）
+
+## 重要业务行须中文行注释
+- 判断 / 折中 / 绕过 / 业务规则 / 性能取舍 —— 这些"为什么这么写"的行须注释
+- 显而易见的代码不需注释（避免噪音）
+
+## 所有注释中文
+- 与代码日志中文一致
+
+## 关联
+- [[编码纪律]] / [[证据驱动与反幻觉]]