soloforge 1.1.47 → 1.1.48

package/templates/build/enforced.md

@@ -111,7 +111,7 @@ checks:
   - id: SEC-07
     executor: regex_pattern_scan
     rule: "禁止 ../ 路径遍历风险"
-    severity: error
+    severity: warning
     check_type: deterministic
     pattern: '/\.\.[\\\/]/'
     languages: [通用]
@@ -163,22 +163,23 @@ 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"
-  # —— 代码架构检查（从 design-gate 迁入，代码实现阶段归属）——
-  - id: ARC-01
+  # —— 日志契约（LOG-ZH，regex 验证中文日志；原 BLD-G03 中文日志部分硬化）——
+  - id: LOG-ZH
     executor: regex_pattern_scan
-    rule: "Controller 禁止包含业务逻辑（计算/校验等应下沉 Service）"
-    severity: error
+    rule: "业务日志须含中文事件名（方便调试观察）；命中=日志字符串无中文字符（纯英文/符号）"
+    severity: warning
     check_type: deterministic
-    pattern: '/\bclass\s+\w*Controller\b[\s\S]{0,500}\b(if|for|while|calculate|compute)\s*\(/'
-    languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Controller 含业务逻辑命中）"]
+    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"
@@ -192,7 +193,7 @@ checks:
   - id: ARC-03
     executor: regex_pattern_scan
     rule: "写操作（save/create/update/delete）必须有 @Transactional"
-    severity: error
+    severity: warning
     check_type: deterministic
     pattern: '/\.(save|insert|update|delete|remove|create)\s*\(/'
     languages: [java]
@@ -212,31 +213,183 @@ checks:
   - id: ARC-06
     executor: regex_pattern_scan
     rule: "前端 API 调用必须封装到 service 层，禁止组件内直接 fetch/axios"
-    severity: error
+    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-07
+  - id: ARC-08
     executor: regex_pattern_scan
-    rule: "禁止 @Autowired + @Lazy 循环依赖"
+    rule: "Service 层禁止直接操作 HttpServletRequest/Response"
     severity: error
     check_type: deterministic
-    pattern: '/@Autowired[\s\S]{0,50}@Lazy|@Lazy[\s\S]{0,50}@Autowired/'
+    pattern: '/\bHttpServletRequest\b|\bHttpServletResponse\b/'
     languages: [java]
-    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无循环依赖命中）"]
+    evidence_required: ["regex_pattern_scan 扫描结果（git diff 变更文件无 Service 操作 HttpServlet 命中）"]
     gate: build-gate
     target: "self"
-  - id: ARC-08
+  # —— 并发安全（CON-*，从 verify/enforced.md 物理归位；gate 本就是 build-gate）——
+  - id: CON-01
     executor: regex_pattern_scan
-    rule: "Service 层禁止直接操作 HttpServletRequest/Response"
+    rule: "共享可变状态必须有并发保护"
     severity: error
     check_type: deterministic
-    pattern: '/\bHttpServletRequest\b|\bHttpServletResponse\b/'
+    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 变更文件无 Service 操作 HttpServlet 命中）"]
+    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
@@ -255,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 零错误，项目构建成功"
@@ -273,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: ["硬编码密钥扫描结果（须为 0）","未鉴权写接口扫描结果（须为 0）","注入防护方案确认","依赖漏洞扫描报告（高危/严重须为 0）"]
+    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: ["数据库设计文档模版", "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//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
+- **职责**（做什么）+ **边界**（不做什么）+ **入参**（含义/约束）+ **出参**（含义）+ **异常**（何时抛）
+
+## 重要业务行须中文行注释
+- 判断 / 折中 / 绕过 / 业务规则 / 性能取舍 —— 这些"为什么这么写"的行须注释
+- 显而易见的代码不需注释（避免噪音）
+
+## 所有注释中文
+- 与代码日志中文一致
+
+## 关联
+- [[编码纪律]] / [[证据驱动与反幻觉]]

package/templates/build//346/265/213/350/257/225/350/256/241/345/210/222.md

@@ -24,6 +24,7 @@ extra:
 
 > **产物定位**：build 阶段必出。定义"测什么、怎么测、什么证据算通过"。
 > **核心纪律**：禁止假验证——E0（无运行时证据）不可接受（[[证据驱动与反幻觉]] 第 5/10 条）。覆盖正常/异常/边界/权限/并发，不只 happy path。
+> **反退化纪律**：每个测试条目（T-*）必须在「测试条目」表中逐行填写真实编号（REQ-*/SLC-*），禁止只列前几行后用「…」省略、禁止用一句话概括代替表格行。
 
 ## 1. 测试范围
 - 关联任务/需求：
@@ -31,12 +32,15 @@ extra:
 - 不在范围内的事项：
 
 ## 2. 测试条目
+
+> 填**真实编号**：REQ-001（需求分析的真实 REQ）、SLC-用户-01（切片规划的真实切片）。build-gate cross_validation 校验测试↔需求的 REQ-* 一致性+覆盖率，占位符 REQ-NNN 会 fail-closed 阻断。
+
 | 编号 | 功能点 | 测试类型 | 覆盖策略 | 关联需求 | 关联切片 | test_phase | 优先级 | Evidence 级别 |
 |------|--------|---------|---------|---------|-----------|-----------|--------|--------------|
-| T-01 | 正常流程 | 集成测试 | 正常路径 | REQ-NNN | SLC-x | red→green | P0 | E1 |
-| T-02 | 参数缺失 | 单元测试 | 错误路径 | REQ-NNN | SLC-x | red→green | P0 | E1 |
-| T-03 | 权限不足 | 集成测试 | 错误路径 | REQ-NNN | SLC-x | red→green | P0 | E2 |
-| T-04 | 边界值 | 单元测试 | 边界场景 | REQ-NNN | SLC-x | combined | P1 | E1 |
+| T-01 | 正常流程 | 集成测试 | 正常路径 | REQ-001 | SLC-用户-01 | red→green | P0 | E1 |
+| T-02 | 参数缺失 | 单元测试 | 错误路径 | REQ-001 | SLC-用户-01 | red→green | P0 | E1 |
+| T-03 | 权限不足 | 集成测试 | 错误路径 | REQ-002 | SLC-用户-01 | red→green | P0 | E2 |
+| T-04 | 边界值 | 单元测试 | 边界场景 | REQ-001 | SLC-用户-01 | combined | P1 | E1 |
 
 > 覆盖策略必含：正常路径 / 错误路径 / 边界 / 权限 / 并发（适用时）。缺一类须说明理由。
 
@@ -69,3 +73,4 @@ extra:
 - [ ] 每条标注 Evidence 级别，无 E0
 - [ ] P0 项有验收标准且执行通过
 - [ ] 失败用例有修复或明确说明
+- [ ] 测试条目表逐行填真实编号，无「…」省略、无一句话概括代替

package/templates/build//347/274/226/347/240/201/347/272/252/345/276/213.md

@@ -34,6 +34,32 @@ extra:
 > 吸收旧的「编码阶段执行」「编码就绪审查」「编码质量」「切片执行纪律」「防御性编码」。
 > 基本功（命名/注释/单一职责/错误处理）见 [[工程纪律]]，不重复。
 
+## 超大系统：先研讨实现策略再动手
+
+开发切片计划 SLC 切片数 ≥ 5（超大系统）时，build 写代码前**必须**先 `sf_work action=deliberate target=code` 与用户研讨实现策略（头脑风暴 + 第一性原理），收敛后把结论总结留痕到 `docs/研讨记录/构建/产物-研讨记录.md`，再 act 写代码。
+
+- 此规则由 build-gate `BLD-DELIB` 确定性门禁兜底——未研讨则 build 阻断，不是软建议
+- 小任务（切片 < 5 或无切片计划）不强制，正常列改动清单即可
+- 研讨重点：切片实现顺序、跨切片共享代码先沉淀、风险切片先行验证
+
+## 工程骨架：首个切片建多工程目录（涉及多端时）
+
+build 域第一个切片（首次 `act target=code`）时，按架构 §6.3 端清单 + intent.yaml `projects` 创建工程目录骨架——每个端一个独立工程目录（`backend/` `client-portal/` `admin-web/` `miniapp/` `shared/`），每个工程目录内建标准 `src/` + 独立 `.gitignore`（按技术栈）+ 各自构建配置（package.json/pom.xml 等）。
+
+- 工程目录结构 = 架构 §6.3 端清单 + intent.yaml `projects`（build scope `allowed_paths` 据此放行）
+- **每个工程独立 `.gitignore`**（不要只在根目录一个）：前端 `node_modules/` `dist/`、Java `target/` `build/`、小程序 `miniprogram_npm/` 等
+- 各工程独立构建配置（package.json/pom.xml/build.gradle），独立依赖、独立构建
+- 单工程项目（纯后端 API）保持根 `src/`，不强制多工程
+
+## 前端骨架先行（涉及 FE-* 端时）
+
+涉及前端端（架构 §6.3 声明 FE-*）的项目，前端骨架切片先于业务页面：每个 FE-* 端先落地路由 / 状态管理 / API service 壳 / 认证拦截器 / 脱敏工具，再填充业务页面。
+
+- 骨架切片须覆盖架构 §6.3 所有 FE-* 端（XVAL-SLC 校验 ARCH-*/FE-* 覆盖）
+- 共享层（shared：类型/API client/工具）先于各端业务沉淀，避免散落
+- 前端 API 调用封装到 service 层，禁止组件内直接 fetch/axios（build-gate ARC-06）
+- Vue3/uni-app 等无内置脚手架的技术栈，配自定义模板合同（`config.scaffold.contracts`）
+
 ## 实现前：先列改动清单（精准修改）
 
 动手前明确（[[工程执行总纲]] 精准修改）：

package/templates/design/API/346/216/245/345/217/243/350/247/204/346/240/274/346/226/207/346/241/243.md

@@ -24,6 +24,12 @@ extra:
 
 > **产物定位**：涉及前后端接口对接时产出（按需）。把接口契约先于实现定清楚，避免前端等后端。
 > **核心纪律**：契约先行（[[编码纪律]]）；每个 endpoint 有验收场景 + 验证证据（[[证据驱动与反幻觉]]）。
+> **反退化纪律**：每个 endpoint 必须完整重复其全部必填结构块，禁止退化——
+> - 禁止「前详后废」（前几个 endpoint 完整、后面的退化成一行文字）
+> - 禁止用一行文字 `**xxx**：…` 代替表格，或省略标 `[Always]` 的必填块（基本信息/响应体字段/错误与副作用/验收场景）
+> - 章节标题必须用 `###`，禁止降级为 `**粗体**`
+> - 禁止「同上格式」「见上文」「…」等偷懒占位
+> 任一 endpoint 缺任一必填块 = 未完成，须补齐后再推进。
 > **完成判定**：见文末，每个 endpoint 须满足。
 
 OpenAPI 权威路径: `docs/api/openapi.yaml`
@@ -96,3 +102,4 @@ OpenAPI 权威路径: `docs/api/openapi.yaml`
 - [ ] 每个验收场景有验证证据（不得为空）
 - [ ] 枚举值定义覆盖所有枚举字段
 - [ ] 涉及前端调用的接口有页面交互映射
+- [ ] 每个 endpoint 都含全部必填表格块（基本信息/响应体字段/错误与副作用/验收场景），无一行文字替代、无偷懒占位