soloforge 1.1.40 → 1.1.43

package/templates/shared//351/205/215/347/275/256/344/274/230/345/205/210/347/272/247.md

@@ -0,0 +1,75 @@
+---
+id: ka-hard-rule-配置优先级规则
+kind: guidance
+title: 配置优先级
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 配置优先级规则
+extra:
+  name: configuration-priority
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - mc-config-precedence
+  hard_blocks:
+    - 配置冲突未裁决
+    - 优先级颠倒
+  fallback: manual_required
+  version: 2.0.0
+  last_reviewed: '2026-06-03'
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-config-precedence
+---
+
+# 配置优先级规则
+
+## 核心约束
+
+1. 配置解析采用三层合并（`resolveConfig`），优先级从高到低：
+   - **探测层**：从项目文件（`package.json`、`pom.xml`、`go.mod` 等）实时推导
+   - **intent 层**：用户在 `.soloforge/intent.yaml` 中显式声明的偏好
+   - **框架约定层**：框架 profile 中的默认值（scope、build_commands 等）
+   - **全局默认层**：`unknown` / 空字符串 / 空数组
+
+2. 可探测字段优先级链（`??` nullish coalescing）：
+   - `tech_stack`：`fingerprint.backend` ?? `intent.tech_stack.backend` ?? `{ lang: "unknown", framework: "unknown" }`
+   - `build_commands`：项目 `scripts` > 框架约定 > `intent.overrides.build_commands` > 空
+   - `scope`：`intent.overrides.scope` > 框架约定 `defaultScope` > `["src/"]`
+
+3. 不可探测字段优先级链：
+   - `product_profile`：`intent.product_profile` ?? `"default"`
+   - `delivery`：`intent.delivery` ?? `{ auto_push: false, auto_pr: false }`
+
+4. 字段缺失 ≠ 空值：intent.yaml 不存在时 `loadIntent` 返回 `{}`，resolver 用 `??` 填充默认值。
+
+5. 探测结果与 intent 声明冲突时，探测胜出。冲突通过 `detectConflicts()` 标记，建议用户移除冗余声明或使用 `overrides` 确认覆盖。
+
+## 阻断行为
+
+- `tech_stack` 全 `unknown` → 阻断（missing: tech_stack）
+- `build_commands` 全空 → 阻断（missing: build_commands）
+- `scope = []` → 不阻断（blacklist mode）
+- `product_profile = "default"` → 不阻断
+- `delivery` 全 `false` → 不阻断
+
+## 适用场景
+
+- 项目初始化（`soloforge init`）
+- 配置查看（`sf_doctor check_type=full`）
+- 配置写入（编辑 `intent.yaml`）
+- 配置检查（`sf_doctor check_type=full`）
+- 运行时配置读取（`resolveProjectConfig`）
+
+## 违规处理
+
+- intent.yaml 声明与探测结果冲突 → warning，建议移除冗余声明或使用 overrides
+- 可探测字段在 intent.yaml 中直接声明 → 允许（标记为过渡性，脚手架完成后可删除）
+- 写入非法字段（`_` 前缀内部字段）→ hard_fail，阻断写入

package/templates/shared//351/205/215/347/275/256/350/220/275/347/233/230/350/276/271/347/225/214.md

@@ -0,0 +1,43 @@
+---
+id: ka-hard-rule-配置落盘边界规则
+kind: guidance
+title: 配置落盘边界
+owner_mechanism: mc-config-write-boundary
+sync_policy: internal
+status: active
+extra:
+  name: configuration-persist-boundary
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: constraint
+  lifecycle_status: active
+  authority: canonical
+  priority: P1
+  consumes:
+    - config_write_boundary
+    - mc-config-resolver
+  hard_blocks:
+    - runtime_inference_persisted
+    - existing_project_write_without_confirm
+  fallback: manual_required
+  required_evidence:
+    - config_resolution_report
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  verification_layer: L2
+  stage: _global
+---
+
+# 配置落盘边界规则
+
+运行时推断、已有项目探测和空项目蓝图必须区分处理。配置解析采用三层合并（探测 > intent.yaml > 框架约定 > 默认），只有用户显式声明的不可探测偏好才写入 intent.yaml。
+
+## 硬规则
+
+- 运行时推断结果（探测的技术栈、构建命令等）不得自动写入 intent.yaml。
+- intent.yaml 只存储用户显式写入的配置字段，不存储自动探测结果。
+- 已有项目写入 `.soloforge/`、`.mcp.json`、`CLAUDE.md` 或 adapter 配置时必须有用户确认。
+- 空项目初始化可以创建 SoloForge 管理文件。
+- 同步模版不得覆盖用户已修改资产。

package/templates/shared//351/230/262/345/255/244/345/262/233/345/256/236/347/216/260.md

@@ -0,0 +1,58 @@
+---
+id: ka-hard-rule-防孤岛实现规则
+kind: guidance
+title: 防孤岛实现
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 防孤岛实现规则
+extra:
+  name: anti-silo-implementation
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - mc-workflow-contract
+  hard_blocks:
+    - 模块无entry_trace
+    - orphan_module
+  fallback: manual_required
+  required_evidence:
+    - main_path_integration
+    - orphan_scan
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-main-path-integration
+---
+
+# 防孤岛实现规则
+
+## 核心原则
+
+新增生产代码不能只证明"文件存在、单测通过"，必须证明它已经进入真实主链路。
+
+## 完成定义
+
+Done = implemented + wired + reachable + observable + verified
+
+## 规则
+
+1. 新增 src/ 代码只被测试导入 → hard_fail
+2. enforced 能力无入口链路 → hard_fail
+3. 只有 registry/index export 引用不得标记为 integrated
+4. 已接入模块必须有集成测试证明真实入口能触发
+5. diagnostic_code 必须能由真实路径产出
+
+## 验收标准
+
+- [ ] 新增模块有 production_imports
+- [ ] entry_traces 包含完整调用链
+- [ ] integration_tests 覆盖真实入口触发
+- [ ] observability_refs 包含可观测证据

package/templates/shared//351/233/266/351/205/215/347/275/256/345/210/235/345/247/213/345/214/226.md

@@ -0,0 +1,65 @@
+---
+id: ka-hard-rule-项目配置解析规则
+kind: guidance
+title: 零配置初始化
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 项目配置解析规则
+extra:
+  name: project-config-resolution
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - mc-zero-config-init
+  hard_blocks:
+    - 配置推断错误
+    - fingerprint 不匹配
+  fallback: manual_required
+  version: 2.0.0
+  last_reviewed: '2026-06-03'
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-zero-config-init
+---
+
+# 项目配置解析规则
+
+## 核心约束
+
+1. **三层配置解析**: `resolveConfig` 合并三个配置层：
+   - **探测层**（`detectFingerprint`）：从项目文件实时推导技术栈、构建命令、scope
+   - **intent 层**（`loadIntent`）：用户在 `.soloforge/intent.yaml` 中的显式声明
+   - **框架约定层**：框架 profile 提供的默认值
+   - 探测层优先于 intent 层（探测 > intent > 约定 > 默认）
+
+2. **禁止自动落盘**: `resolveConfig` 的结果不自动写入 intent.yaml
+   - 技术栈、构建命令等可探测字段由项目文件推导，无需存储
+   - 只有用户显式写入的字段才存储到 intent.yaml；自动探测结果（技术栈、构建命令）不写入
+   - `--dry-run` 模式始终可用
+
+3. **配置来源**:
+   - 已有 `.soloforge/intent.yaml` → 合并 intent 声明 + 项目文件探测
+   - 仅有 `config.yaml`（旧格式）→ 自动迁移为 intent.yaml（`migrateFromV1`）
+   - 两者都不存在 → 纯探测模式（从项目文件推导全部配置）
+
+4. **字段缺失语义**: intent.yaml 中缺失的字段 = "未声明"，使用探测或默认值填充
+   - 不缺失 ≠ 空值，`loadIntent` 不存在时返回 `{}`，resolver 用 `??` 处理
+
+5. **配置完整性检查**: `checkConfigReadiness` 阻断场景：
+   - `tech_stack` 全 `unknown` → 阻断
+   - `build_commands` 全空 → 阻断
+   - `scope` / `product_profile` / `delivery` / `repos` → 不阻断
+
+## 验证要点
+
+- `init` 不创建用户未确认的配置文件
+- 探测结果与实际项目类型一致（内容验证，非文件存在性检查）
+- 空项目使用纯探测模式而非猜测配置
+- 配置冲突（intent 与探测矛盾）通过 `detectConflicts` 正确标记

package/templates/shared//351/252/214/346/224/266/346/250/241/347/211/210/350/276/223/345/207/272/345/245/221/347/272/246.md

@@ -0,0 +1,86 @@
+---
+id: ka-hard-rule-验收模版输出契约规则
+kind: guidance
+title: 验收模版输出契约
+owner_mechanism: mc-standard-asset-contract
+sync_policy: internal
+status: active
+extra:
+  name: acceptance-template-output-contract
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: constraint
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - standard_asset_contract
+    - design_artifact_pack
+    - repair_reverify_directive
+  hard_blocks:
+    - template_contract_violation
+    - draft_artifact_consumed
+    - missing_authoritative_asset
+  fallback: manual_required
+  required_evidence:
+    - template_contract_result
+    - authoritative_asset
+    - repair_reverify_result
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  verification_layer: L2
+  stage: _global
+---
+
+# 验收模版输出契约规则
+
+## 触发条件
+
+当任务产出正式设计文档、架构设计、数据库设计、API 接口规格、原型说明或验收报告时，必须按标准资产契约验收。
+
+## 适用范围
+
+- 架构设计文档（01-架构设计文档.md）
+- 数据库设计文档（design/01-数据库设计文档.md）
+- API 接口规格（design/02-API接口规格文档.md）
+- 设计一致性验收报告（audits/01-设计一致性验收报告.md）
+- 原型说明文档
+
+## 契约要求
+
+每个 P0 模版输出必须满足:
+
+1. **章节检查**: 必填章节存在、顺序合理、不得只有空标题。
+2. **表格检查**: 必填表格存在、表头正确、行内容覆盖必要对象。
+3. **字段检查**: API/数据/追踪字段具备类型、必填、来源、说明、示例、校验规则、错误语义。
+4. **权威资产检查**: 必须引用并对齐 OpenAPI、SQL/migration 等机器权威资产。
+5. **语义检查**: Mermaid 图、字段、实体与当前业务相关，不得用无关内容凑数。
+
+## API 字段表最小列
+
+字段名 / 类型 / 必填 / 来源 / 说明 / 示例 / 校验规则 / 错误语义
+
+## Mermaid 检查规则
+
+- fence 语法合法。
+- 图类型符合模版要求（sequenceDiagram、flowchart 等）。
+- 图内容与当前业务相关。
+
+## 修复闭环
+
+模版契约验收失败必须进入修复重验:
+
+1. sf_gate 报告缺口和诊断码。
+2. 修复后重新 sf_gate。
+3. 仍然失败则继续循环或请求用户确认。
+4. 修复期间交付被阻断。
+
+## 草稿状态
+
+草稿必须显式标记 `draft`、`not_for_implementation` 或 `needs_template_verification`。草稿不进入编码消费。
+
+## 低风险跳过
+
+普通 bugfix、样式修复、只读解释和小范围改动不触发模版契约验收。

package/templates/shared//351/252/214/350/257/201/345/221/275/344/273/244/347/224/237/346/210/220.md

@@ -0,0 +1,59 @@
+---
+id: ka-pattern-verify_command_generation
+kind: knowledge
+title: 验证命令生成
+sync_policy: internal
+status: active
+extra:
+  name: verify_command_generation
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-engine-runtime
+---
+
+## 决策规则
+
+- generateVerifyCommands 根据项目类型生成编译和测试命令
+- 三个分支: config（有 intent.yaml）、doc-only（无代码项目）、repo（标准项目）
+- repo 分支通过 resolveConfig 推导技术栈和构建命令
+- config 分支使用 intent.yaml 中的 overrides.build_commands 覆盖框架约定
+- 生成的命令必须可执行，且覆盖编译 + 测试两个阶段
+- 边界项目（无 package.json）必须有 fallback 处理
+
+## 验收项
+
+- [AC-01] config/doc-only/repo 三分支覆盖
+- [AC-02] 生成的命令格式正确
+- [AC-03] 边界项目有 fallback
+- [AC-04] 自定义命令模版覆盖默认命令
+
+## 何时使用
+
+编译和测试命令是质量门禁的基础
+
+## 是否 hard block
+
+是。此能力为 enforced 状态，违规即 hard fail 阻断流程。
+
+## 证据要求
+
+- config/doc-only/repo 三分支测试通过
+- 边界项目（无 package.json）验证通过
+-
+
+## 人工确认/降级边界
+
+- enforced 能力不可跳过，违反即阻断
+- 降级需经 治理运行时 + 人工确认，提供 escape report 证据

package/templates/shared//351/252/214/350/257/201/345/245/221/347/272/246.md

@@ -0,0 +1,59 @@
+---
+id: ka-hard-rule-验证契约规则
+kind: guidance
+title: 验证契约
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 验证契约规则
+extra:
+  name: verification-contract
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - mc-task-context-lifecycle
+  hard_blocks:
+    - 验证未通过
+    - 证据缺失
+  fallback: manual_required
+  required_evidence:
+    - verification_evidence
+    - test_results
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-verifier
+---
+
+# 验证契约规则
+
+## 核心原则
+
+验证策略由 execution_shape 决定，不同执行形态使用不同验证强度。
+
+## 验证策略
+
+1. **code_execution**: 完整 build + test
+2. **single_artifact/source_extraction**: 轻量检查
+3. **direct_answer**: 无需验证
+
+## 规则
+
+1. 验证结果必须保存到 task_context 才能标记 done/learning
+2. evidence level 必须达到 E1 以上
+3. 验证命令必须覆盖所有 changed_files
+4. 验证失败时进入 repair_reverify 循环
+
+## 验收标准
+
+- [ ] generateVerifyCommands 根据 execution_shape 选择策略
+- [ ] VerifyResult 包含 evidence 和 coverage
+- [ ] 验证结果保存到 task_context
+- [ ] repair_reverify 循环有 max_attempts 限制

package/templates/verify/Docker/351/203/250/347/275/262.md

@@ -0,0 +1,50 @@
+---
+id: ka-pattern-docker-deployment
+kind: knowledge
+title: Docker部署
+sync_policy: copy_to_project
+status: active
+extra:
+  name: docker-deployment
+  scope:
+    - backend
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-general-pattern
+---
+
+## 决策规则
+- 每次部署必须从源码全新构建镜像，禁止 docker commit、容器内文件编辑、docker exec 安装依赖
+- Bug 修复后必须重新构建镜像并重新部署后再验证，禁止在旧容器中验证修复
+- 前端禁止复制预构建的 dist/ 目录，必须在 Dockerfile 内完成构建
+- docker compose up 必须能一键启动所有服务并通过健康检查
+- 若浏览器验证发现容器未运行当前代码，必须自动重建并重新部署
+- Dockerfile 必须使用多阶段构建（build → runtime），禁止在最终镜像中包含构建工具和源码
+- 容器必须配置 HEALTHCHECK 指令，编排工具（K8s/Docker Compose）依赖健康检查做流量管理
+- 容器必须设置资源限制（memory limit、CPU limit），防止单个容器耗尽主机资源
+- 镜像版本禁止使用 :latest 标签部署，必须指定明确版本号（如 :1.2.3）
+- 敏感配置（密码、密钥）禁止写入 Dockerfile 或镜像，必须通过环境变量或 Secret 注入
+- 容器必须以非 root 用户运行（USER app），禁止默认 root 运行
+
+## 验收项
+- [AC-01] 镜像从源码全新构建
+- [AC-02] 无 docker commit 或热补丁
+- [AC-03] docker compose 一键启动通过健康检查
+- [AC-04] 修复后重建镜像再验证
+- [AC-05] 多阶段构建
+- [AC-06] 有 HEALTHCHECK 配置
+- [AC-07] 镜像指定版本号（非 latest）
+- [AC-08] 敏感配置通过环境变量/Secret 注入
+- [AC-09] 非 root 用户运行

package/templates/verify/POC/347/273/223/350/256/272.md

@@ -0,0 +1,59 @@
+---
+id: ka-artifact_template-POC结论模版
+kind: artifact
+title: POC结论
+sync_policy: copy_to_project
+status: active
+extra:
+  name: poc-conclusion
+  scope:
+    - backend
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits:
+    - acceptance_report
+  type: artifact
+  domain: verify
+  requires_context: []
+  stage: verify
+  owner_mechanism: mc-generic-artifact
+---
+
+# POC 结论报告
+
+## 1. 验证目标
+- 核心验证问题：
+- 成功标准：
+
+## 2. 候选方案
+| 方案 | 版本 | 许可证 | 社区活跃度 |
+|------|------|--------|-----------|
+| A | | | |
+| B | | | |
+
+## 3. 评估维度
+| 维度 | 权重 | 方案A评分 | 方案B评分 | 说明 |
+|------|------|----------|----------|------|
+| 性能 | | | | |
+| 易用性 | | | | |
+| 生态兼容 | | | | |
+| 学习成本 | | | | |
+| 维护成本 | | | | |
+
+## 4. 关键发现
+- 发现的技术限制：
+- 遇到的坑和解决方案：
+- 性能基准数据：
+
+## 5. 结论
+- **推荐方案**：
+- **推荐理由**：
+- **遗留风险**：
+- **后续关注点**：

package/templates/verify/React/345/210/227/350/241/250/350/241/250/346/240/274.md

@@ -0,0 +1,47 @@
+---
+id: ka-pattern-react-list-table
+kind: knowledge
+title: React列表表格
+sync_policy: copy_to_project
+status: active
+extra:
+  name: react-list-table
+  scope:
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-frontend-pattern
+---
+
+## 决策规则
+- 必须使用后端分页，禁止前端对全量数据做分页
+- 列定义必须独立于页面组件（columns.tsx 或配置对象）
+- 删除操作必须有二次确认弹窗
+- 搜索触发后必须自动重置到第一页
+- 工具栏操作（批量删除、导出）必须有 loading 状态
+- 表格数据加载必须使用服务端分页和排序，禁止全量加载前端分页
+- 表格必须有 loading 骨架屏和空状态提示，不能只显示空白
+- 表格操作列按钮必须有二次确认（删除等危险操作）
+- 表格列定义必须抽取为独立配置（columns 数组），禁止写在 JSX 模版中
+- 表格行选择和批量操作必须有明确的已选计数和清空功能
+
+## 验收项
+- [AC-01] 使用后端分页，前端不缓存全量数据
+- [AC-02] 列定义独立于页面组件
+- [AC-03] 删除操作有确认弹窗
+- [AC-04] 搜索触发后重置到第一页
+- [AC-05] 服务端分页排序
+- [AC-06] loading/空状态处理
+- [AC-07] 危险操作二次确认
+- [AC-08] 批量操作有已选计数

package/templates/verify/React/347/212/266/346/200/201/347/256/241/347/220/206.md

@@ -0,0 +1,46 @@
+---
+id: ka-pattern-react-state-management
+kind: knowledge
+title: React状态管理
+sync_policy: copy_to_project
+status: active
+extra:
+  name: react-state-management
+  scope:
+    - frontend
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: supporting
+  priority: P2
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  consumes: []
+  emits: []
+  type: knowledge
+  domain: verify
+  verification_layer: L2
+  stage: verify
+  owner_mechanism: mc-frontend-pattern
+---
+
+## 决策规则
+- 组件内状态用 useState，禁止滥用全局 Context
+- 跨组件共享状态用 Context + useReducer，禁止 props 层层传递超过 3 层
+- 全局持久化状态（用户、权限）通过 Context + localStorage 提供
+- API 数据必须在 custom hook 中局部管理，禁止存入全局 store
+- 禁止引入 Redux/Zustand 除非项目已有约定
+- 全局状态必须使用状态管理库（Zustand/Redux/Jotai），禁止通过 props drilling 传递超过 2 层
+- 服务端状态必须使用 TanStack Query/SWR 管理，禁止手动 useState + useEffect 获取数据
+- 状态更新必须使用不可变方式（immer/spread），禁止直接 mutate state
+- 全局状态必须按领域分片（slice/store），禁止单个巨大 store 包含所有数据
+- 持久化状态（如用户偏好）必须序列化到 localStorage，应用启动时恢复
+
+## 验收项
+- [AC-01] 组件内状态用 useState，未滥用 Context
+- [AC-02] 全局状态通过 Context 提供
+- [AC-03] API 数据在 custom hook 中管理
+- [AC-04] 无 useEffect 依赖项导致的无限循环
+- [AC-05] 全局状态使用状态管理库
+- [AC-06] 服务端状态使用 TanStack Query
+- [AC-07] 状态更新不可变方式