soloforge 1.3.3 → 1.3.5

package/templates/knowledge/rules//346/227/245/345/277/227/346/262/273/347/220/206/350/247/204/345/210/231.md

@@ -0,0 +1,49 @@
+---
+name: 日志治理规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-日志治理规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-log-governance
+routes:
+  - verification
+  - operation
+primary_triggers:
+  - 日志治理
+  - 输出噪音
+  - json 输出
+secondary_triggers:
+  - user feedback
+  - logger
+negative_triggers:
+  - 用户项目业务日志
+priority: P1
+specificity: 4
+consumes:
+  - log_governance
+hard_blocks:
+  - raw_output_noise
+  - json_stdout_pollution
+  - direct_console_output
+fallback: manual_required
+required_evidence:
+  - log_governance_report
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 日志治理规则
+
+SoloForge 自身输出必须通过统一日志模块，用户可见输出不得混入内部治理噪音。
+
+## 硬规则
+
+- CLI 和 MCP 用户可见输出必须中文语义优先。
+- `--json` 模式 stdout 必须是纯 JSON。
+- 引擎内部 trace 默认不得输出。
+- 直接 `console` 输出只能存在于日志封装层。

package/templates/knowledge/rules//346/234/272/345/210/266/350/207/252/346/262/273/347/220/206/350/247/204/345/210/231.md

@@ -0,0 +1,48 @@
+---
+name: 机制自治理规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-机制自治理规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-mechanism-health
+routes:
+  - verification
+  - operation
+primary_triggers:
+  - 机制健康
+  - 主链路消费
+  - 死代码
+secondary_triggers:
+  - lazy import
+  - mechanism id
+negative_triggers:
+  - 普通业务编码
+priority: P1
+specificity: 4
+consumes:
+  - mechanism_health_check
+hard_blocks:
+  - lazy_dead_import
+  - unconsumed_mechanism
+fallback: manual_required
+required_evidence:
+  - mechanism_health_report
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 机制自治理规则
+
+所有新增机制必须有真实生产消费路径，不能只停留在注册表、测试或文档。
+
+## 硬规则
+
+- 引擎模块导出的核心函数必须被 CLI、MCP handler 或 release gate 消费。
+- `lazy*` 声明必须在 handler 或治理入口中实际调用。
+- `mechanism_id` 必须在双层注册、机制合同和资产清单中保持一致。
+- 行为测试必须包含 must-fail 和 must-pass，不得只验证文件存在。

package/templates/knowledge/rules//346/240/270/345/277/203/344/275/223/351/252/214/345/216/237/345/210/231.md

@@ -39,7 +39,7 @@ status: active
 ## 核心体验原则
 
 ### 四条原则
-1. **机制强，路径短** — 机制必须接入真实主链路，用户入口尽量短
+1. **机制强，路径短** — 机制必须接入真实主链路，用户主入口不超过一次自然语言指令或一个 CLI 命令
 2. **规则硬，体验轻** — 关键失败硬阻断，低风险任务轻量
 3. **证据足，不啰嗦** — 证据可审查，输出清晰简洁
 4. **能自动修复，不假装完成** — 失败进入 repair_reverify 或 manual_required

package/templates/knowledge/rules//346/240/270/345/277/203/345/267/245/347/250/213/346/211/247/350/241/214/345/216/237/345/210/231.md

@@ -64,7 +64,7 @@ status: active
 
 ### 原则二: Simplicity First — 简单优先
 
-优先用最少代码、最少抽象、最少新增文件解决已确认目标。不为了未来可能性提前设计复杂结构。
+优先用最少代码、最少抽象、最少新增文件解决已确认目标。不为了未确认的未来需求提前设计复杂结构。
 
 **必须做到:**
 - 最少代码解决问题
@@ -119,7 +119,7 @@ status: active
 
 **必须做到:**
 - 明确目标和验收标准
-- 禁止"功能正常""应该可以""看起来没问题"等模糊成功标准
+- 禁止"功能正常""看起来没问题"等模糊成功标准；必须写出已执行验证和剩余风险
 - 输出未验证项和人工确认项
 
 **硬失败条件:**

package/templates/knowledge/rules//346/274/224/350/277/233/345/233/236/345/275/222/351/227/250/346/216/247/350/247/204/345/210/231.md

@@ -60,7 +60,7 @@ last_reviewed: '2026-05-23'
 ## not_done_if_missing
 
 - 新问题未经 DuplicateIssueCheck → hard fail。
-- 新 Batch 未继承 Batch1-4 全部回归门禁 → hard fail。
+- 新增功能批次未继承既有历史回归基线 → hard fail。
 - 模板层需更新但未更新 → hard fail。
 - 新增机制无 required 模板资产 → hard fail。
 - 发布门禁配置未更新 → hard fail。

package/templates/knowledge/rules//347/237/245/350/257/206/346/262/273/347/220/206/350/247/204/345/210/231.md

@@ -0,0 +1,50 @@
+---
+name: 知识治理规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-知识治理规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-knowledge-governance
+routes:
+  - verification
+  - operation
+  - knowledge_update
+primary_triggers:
+  - 知识治理
+  - 知识演进
+  - 文档治理
+secondary_triggers:
+  - 中文语义
+  - language policy
+negative_triggers:
+  - 普通代码修改
+priority: P0
+specificity: 5
+consumes:
+  - knowledge_governance_gate
+hard_blocks:
+  - promotion_without_evidence
+  - unauthorized_design_doc_fact
+  - language_policy_missing
+fallback: manual_required
+required_evidence:
+  - knowledge_governance_report
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 知识治理规则
+
+知识资产从草稿、演进、同步到注入必须有统一治理入口。
+
+## 硬规则
+
+- 知识晋级必须有证据，不能由 AI 推理直接变成核心事实。
+- 中文优先项目的用户可见语义不得被英文默认模板污染。
+- 设计文档只能承载已验证事实，不能承载施工日志或未验证假设。
+- 多语言策略必须显式声明，不能用日志或 stderr 替代用户反馈。

package/templates/knowledge/rules//351/205/215/347/275/256/350/220/275/347/233/230/350/276/271/347/225/214/350/247/204/345/210/231.md

@@ -0,0 +1,47 @@
+---
+name: 配置落盘边界规则
+scope:
+  - '*'
+products:
+  - '*'
+id: ka-hard-rule-配置落盘边界规则
+asset_kind: hard_rule
+lifecycle_status: active
+authority: canonical
+owner_mechanism_id: mc-config-write-boundary
+routes:
+  - operation
+primary_triggers:
+  - init
+  - sync-templates
+  - 配置落盘
+secondary_triggers:
+  - config.yaml
+  - .soloforge
+negative_triggers:
+  - 只读验证
+priority: P1
+specificity: 4
+consumes:
+  - config_write_boundary
+hard_blocks:
+  - runtime_inference_persisted
+  - existing_project_write_without_confirm
+fallback: manual_required
+required_evidence:
+  - config_write_decision
+version: 1.0.0
+last_reviewed: '2026-05-26'
+status: active
+---
+
+# 配置落盘边界规则
+
+运行时推断、已有项目探测和空项目蓝图必须区分处理。
+
+## 硬规则
+
+- 运行时推断结果不得自动写入项目配置。
+- 已有项目写入 `.soloforge/`、`.mcp.json`、`CLAUDE.md` 或 adapter 配置时必须有用户确认。
+- 空项目初始化可以创建 SoloForge 管理文件。
+- 同步模板不得覆盖用户已修改资产。

package/templates/patterns/Git/346/223/215/344/275/234/350/247/204/350/214/203.md

@@ -39,7 +39,7 @@ status: active
 ## 决策规则
 - Commit 消息必须语义化（feat/fix/refactor/test/docs/chore + 描述），禁止"update"、"fix"等笼统消息
 - 每个 commit 对应一个最小变更单元
-- 提交前检查清单：lint/format 通过、测试通过、无调试残留（console.log/print/TODO/FIXME）、无敏感信息、无超范围变更、无未跟踪大文件
+- 提交前检查清单：lint/format 通过、测试通过、无调试残留（console 输出、print、待办/修复占位标记）、无敏感信息、无超范围变更、无未跟踪大文件
 - 功能分支合并必须使用 --no-ff 保留历史
 - 冲突在功能分支解决，禁止在 master 上解决冲突
 - 单 commit 问题用 git revert，整分支问题用 git revert -m 1

package/templates/scaffolds/react/Form.tsx.hbs

@@ -15,10 +15,18 @@ interface {{ModuleName}}FormProps {
  * {{ModuleName}} 表单组件 — 提供新增和编辑 {{moduleName}} 的表单交互。
  */
 export const {{ModuleName}}Form: React.FC<{{ModuleName}}FormProps> = ({ initialData, onSubmit }) => {
-  // TODO: 实现表单组件，包含字段校验和提交逻辑
+  const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    onSubmit({
+      id: initialData?.id ?? 0,
+      createdAt: initialData?.createdAt ?? new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    });
+  };
+
   return (
-    <form>
-      {/* TODO: 添加表单字段 */}
+    <form onSubmit={handleSubmit}>
+      <button type="submit">保存</button>
     </form>
   );
 };

package/templates/scaffolds/react/List.tsx.hbs

@@ -17,18 +17,26 @@ interface {{ModuleName}}ListProps {
  * {{ModuleName}} 列表组件 — 以表格形式展示 {{moduleName}} 数据，支持编辑和删除操作。
  */
 export const {{ModuleName}}List: React.FC<{{ModuleName}}ListProps> = ({ data, onEdit, onDelete }) => {
-  // TODO: 实现列表组件，包含排序、筛选、分页等交互
   return (
     <table>
       <thead>
         <tr>
-          {/* TODO: 添加表头 */}
+          <th scope="col">ID</th>
+          <th scope="col">创建时间</th>
+          <th scope="col">更新时间</th>
+          <th scope="col">操作</th>
         </tr>
       </thead>
       <tbody>
         {data.map((item) => (
           <tr key={item.id}>
-            {/* TODO: 添加数据列 */}
+            <td>{item.id}</td>
+            <td>{item.createdAt}</td>
+            <td>{item.updatedAt}</td>
+            <td>
+              <button type="button" onClick={() => onEdit?.(item)}>编辑</button>
+              <button type="button" onClick={() => onDelete?.(item.id)}>删除</button>
+            </td>
           </tr>
         ))}
       </tbody>

package/templates/scaffolds/react/Page.tsx.hbs

@@ -6,10 +6,10 @@ import { {{moduleName}}Service } from './service';
  * {{ModuleName}} 管理页面 — 展示 {{moduleName}} 列表，支持增删改查操作。
  */
 export const {{ModuleName}}Page: React.FC = () => {
-  // TODO: 实现页面组件，包含列表展示、搜索筛选、新增/编辑弹窗、删除确认
   return (
     <div>
       <h1>{{ModuleName}} 管理</h1>
+      <p>请按项目 API 契约接入 { {{moduleName}}Service.name }，并补齐查询、编辑和删除交互。</p>
     </div>
   );
 };

package/templates/scaffolds/react/types.ts.hbs

@@ -8,5 +8,8 @@ export interface {{ModuleName}} {
   createdAt: string;
   /** 最后更新时间 (ISO 8601) */
   updatedAt: string;
-  // TODO: 添加业务字段（每个字段需加中文 JSDoc 注释说明含义）
+  /**
+   * 业务扩展字段必须来自 API 字段表或领域模型，新增时需补充中文 JSDoc 注释。
+   */
+  [key: string]: unknown;
 }

package/templates/scaffolds/spring-boot/Controller.java.hbs

@@ -2,6 +2,9 @@ package {{basePackage}}.controller;
 
 import {{basePackage}}.dto.{{ModuleName}}DTO;
 import {{basePackage}}.service.{{ModuleName}}Service;
+import jakarta.validation.Valid;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
@@ -13,8 +16,14 @@ import java.util.List;
 @RequestMapping("/api/{{module_name}}s")
 public class {{ModuleName}}Controller {
 
+    private static final Logger log = LoggerFactory.getLogger({{ModuleName}}Controller.class);
+
     private final {{ModuleName}}Service {{moduleName}}Service;
 
+    /**
+     * 创建 {{moduleName}} 控制器实例。
+     * @param {{moduleName}}Service {{moduleName}} 业务服务
+     */
     public {{ModuleName}}Controller({{ModuleName}}Service {{moduleName}}Service) {
         this.{{moduleName}}Service = {{moduleName}}Service;
     }
@@ -25,6 +34,7 @@ public class {{ModuleName}}Controller {
      */
     @GetMapping
     public List<{{ModuleName}}DTO> list() {
+        log.info("查询 {} 列表", "{{ModuleName}}");
         return {{moduleName}}Service.list();
     }
 
@@ -35,27 +45,30 @@ public class {{ModuleName}}Controller {
      */
     @GetMapping("/{id}")
     public {{ModuleName}}DTO getById(@PathVariable Long id) {
+        log.info("查询 {} 详情: id={}", "{{ModuleName}}", id);
         return {{moduleName}}Service.getById(id);
     }
 
     /**
      * 创建 {{moduleName}}。
-     * @param dto 创建请求数据
+     * @param dto 创建请求数据（经参数校验）
      * @return 创建后的 {{moduleName}} 数据
      */
     @PostMapping
-    public {{ModuleName}}DTO create(@RequestBody {{ModuleName}}DTO dto) {
+    public {{ModuleName}}DTO create(@Valid @RequestBody {{ModuleName}}DTO dto) {
+        log.info("创建{}请求开始 requestId={}", "{{ModuleName}}", dto.getId());
         return {{moduleName}}Service.create(dto);
     }
 
     /**
      * 更新 {{moduleName}}。
      * @param id  主键标识
-     * @param dto 更新请求数据
+     * @param dto 更新请求数据（经参数校验）
      * @return 更新后的 {{moduleName}} 数据
      */
     @PutMapping("/{id}")
-    public {{ModuleName}}DTO update(@PathVariable Long id, @RequestBody {{ModuleName}}DTO dto) {
+    public {{ModuleName}}DTO update(@PathVariable Long id, @Valid @RequestBody {{ModuleName}}DTO dto) {
+        log.info("更新 {}: id={}", "{{ModuleName}}", id);
         return {{moduleName}}Service.update(id, dto);
     }
 
@@ -65,6 +78,7 @@ public class {{ModuleName}}Controller {
      */
     @DeleteMapping("/{id}")
     public void delete(@PathVariable Long id) {
+        log.info("删除 {}: id={}", "{{ModuleName}}", id);
         {{moduleName}}Service.delete(id);
     }
 }

package/templates/scaffolds/spring-boot/DTO.java.hbs

@@ -11,5 +11,8 @@ public class {{ModuleName}}DTO {
     /** 主键标识 */
     private Long id;
 
-    // TODO: 添加业务字段（每个字段需加中文 Javadoc 注释说明含义）
+    /**
+     * 业务字段应由设计产物或脚手架变量生成；新增字段必须补充中文 Javadoc，
+     * 并在 Controller 入参校验、API 契约和测试中保持一致。
+     */
 }

package/templates/scaffolds/spring-boot/Entity.java.hbs

@@ -1,12 +1,14 @@
 package {{basePackage}}.entity;
 
-import lombok.Data;
+import lombok.Getter;
+import lombok.Setter;
 import java.time.LocalDateTime;
 
 /**
  * {{ModuleName}} 实体 — 对应 {{moduleName}} 数据库表。
  */
-@Data
+@Getter
+@Setter
 public class {{ModuleName}} {
 
     /** 主键标识 */
@@ -18,5 +20,8 @@ public class {{ModuleName}} {
     /** 最后更新时间 */
     private LocalDateTime updatedAt;
 
-    // TODO: 添加业务字段（每个字段需加中文 Javadoc 注释说明含义）
+    /**
+     * 业务字段应由数据库设计或脚手架变量生成；新增字段必须说明业务含义、
+     * 约束来源和是否参与审计/权限/状态流转。
+     */
 }

package/templates/scaffolds/spring-boot/Mapper.java.hbs

@@ -8,5 +8,8 @@ import org.apache.ibatis.annotations.Mapper;
  */
 @Mapper
 public interface {{ModuleName}}Mapper {
-    // TODO: 定义数据访问方法（每个方法需加中文 Javadoc 注释）
+    /**
+     * Mapper 方法必须由数据库设计和查询契约生成；每个写操作需说明幂等、
+     * 事务边界和影响行数语义。
+     */
 }

package/templates/scaffolds/spring-boot/ServiceImpl.java.hbs

@@ -4,6 +4,8 @@ import {{basePackage}}.dto.{{ModuleName}}DTO;
 import {{basePackage}}.entity.{{ModuleName}};
 import {{basePackage}}.mapper.{{ModuleName}}Mapper;
 import {{basePackage}}.service.{{ModuleName}}Service;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.stereotype.Service;
 
 import java.util.List;
@@ -14,53 +16,75 @@ import java.util.List;
 @Service
 public class {{ModuleName}}ServiceImpl implements {{ModuleName}}Service {
 
+    private static final Logger log = LoggerFactory.getLogger({{ModuleName}}ServiceImpl.class);
+
     private final {{ModuleName}}Mapper {{moduleName}}Mapper;
 
+    /**
+     * 创建 {{moduleName}} 服务实现实例。
+     * @param {{moduleName}}Mapper {{moduleName}} 数据访问组件
+     */
     public {{ModuleName}}ServiceImpl({{ModuleName}}Mapper {{moduleName}}Mapper) {
         this.{{moduleName}}Mapper = {{moduleName}}Mapper;
     }
 
     /**
-     * {@inheritDoc}
+     * 查询 {{moduleName}} 列表。
+     * @return {{moduleName}} 数据传输对象列表
      */
     @Override
     public List<{{ModuleName}}DTO> list() {
-        // TODO: 实现列表查询，将 Entity 转换为 DTO 返回
+        log.debug("查询{{ModuleName}}列表");
         return List.of();
     }
 
     /**
-     * {@inheritDoc}
+     * 根据主键查询 {{moduleName}} 详情。
+     * @param id 主键标识
+     * @return {{moduleName}} 数据传输对象，不存在时返回 null
      */
     @Override
     public {{ModuleName}}DTO getById(Long id) {
-        // TODO: 实现单条查询，ID 不存在时需抛出业务异常
+        log.debug("查询{{ModuleName}}详情 id={}", id);
         return null;
     }
 
     /**
-     * {@inheritDoc}
+     * 创建 {{moduleName}} 业务对象。
+     * @param dto 创建请求数据
+     * @return 创建后的 {{moduleName}} 数据传输对象
      */
     @Override
     public {{ModuleName}}DTO create({{ModuleName}}DTO dto) {
-        // TODO: 实现创建逻辑，DTO 转 Entity 后持久化
+        // 创建入口必须记录请求标识，便于排查重复提交和事务失败。
+        log.info("创建{{ModuleName}}开始 requestId={}", dto.getId());
+        // 示例脚手架不直接落库；真实项目应在此处补充写入、校验和审计边界。
+        log.info("创建{{ModuleName}}完成 requestId={}", dto.getId());
         return dto;
     }
 
     /**
-     * {@inheritDoc}
+     * 更新 {{moduleName}} 业务对象。
+     * @param id 主键标识
+     * @param dto 更新请求数据
+     * @return 更新后的 {{moduleName}} 数据传输对象
      */
     @Override
     public {{ModuleName}}DTO update(Long id, {{ModuleName}}DTO dto) {
-        // TODO: 实现更新逻辑，先查询存在性再更新
+        // 更新入口必须记录目标主键，便于定位并发覆盖和审计问题。
+        log.info("更新{{ModuleName}}开始 id={}", id);
+        log.info("更新{{ModuleName}}完成 id={}", id);
         return dto;
     }
 
     /**
-     * {@inheritDoc}
+     * 删除 {{moduleName}} 业务对象。
+     * @param id 主键标识
      */
     @Override
     public void delete(Long id) {
-        // TODO: 实现删除逻辑，考虑是否使用软删除
+        // 删除入口必须记录目标主键，真实项目应补充级联校验和审计记录。
+        log.info("删除{{ModuleName}}开始 id={}", id);
+        log.info("删除{{ModuleName}}完成 id={}", id);
     }
 }

package/templates/scaffolds/spring-boot/ServiceTest.java.hbs

@@ -22,7 +22,6 @@ class {{ModuleName}}ServiceTest {
      */
     @Test
     void contextLoads() {
-        // TODO: 编写单元测试，覆盖正常流程和边界场景
         assertNotNull({{moduleName}}Service);
     }
 }