soloforge 1.1.46 → 1.1.47

package/templates/operate//344/270/212/347/272/277/350/247/202/345/257/237.md

@@ -1,57 +1,78 @@
 ---
-id: ka-rule-domain-operate-rollout-monitoring
+id: ka-guidance-上线观察
 kind: guidance
 title: 上线观察
+sync_policy: copy_to_project
+status: active
 triggers:
   - 上线
   - 观察
   - 监控
   - rollout
-sync_policy: copy_to_project
-status: active
+  - 灰度
+  - 发布
+  - 回滚
+  - 熔断
+  - 发布后
+target_artifact:
+  - deploy_config
+  - release_note
 extra:
-  updated_at: '2026-06-15'
-  lifecycle_status: active
   name: rollout-monitoring
   scope:
     - '*'
   products:
-    - deploy_config
-    - release_note
-  type: constraint
-  version: 1.0.0
-  last_reviewed: '2026-06-11'
-  domain:
-    - operate
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 2.0.0
+  last_reviewed: '2026-06-17'
   verification_layer: L2
   stage: operate
+  domain: operate
   owner_mechanism: mc-domain-operate
 ---
 
-## 上线观察规则
+# 上线观察：发布后怎么盯、什么时候回滚
+
+> operate-gate 的 OPR-G01~05 是确定性门禁；本 guidance 是发布值守的方法。
+> [[开发者宪法]]：破坏性/线上操作必须可回滚、有人盯。
+
+## 灰度发布
+
+- 小流量先上（1% → 10% → 50% → 100%），每档观察一个周期
+- 每档观察指标无异常再放量
+- 灰度期间保留快速回滚能力
+
+## 观察指标（对应 OPR-G01~03）
+
+- **错误率**：5xx 在基线 ±20% 内（OPR-G01）
+- **延迟**：P99 不超基线 1.5 倍（OPR-G02）
+- **新错误模式**：日志无部署前不存在的错误（OPR-G03）
+- **业务指标**：核心业务量/转化率无异常下跌
 
-### 观察指标
+## 熔断回滚
 
-1. **错误率监控**
-   - 上线后 15 分钟内 5xx 错误率不得超过基线的 2 倍
-   - 新增的错误码必须立即通知
+回滚触发条件（命中任一立即回滚，不要犹豫）：
+- 错误率超基线 2 倍且持续
+- P99 超基线 3 倍
+- 业务核心指标崩跌
+- 数据不一致告警
 
-2. **延迟监控**
-   - P99 延迟不得超过基线的 1.5 倍
-   - 关键接口响应时间必须持续观察 30 分钟
+回滚操作：
+- 按预演过的回滚方案执行（OPR-G04，总耗时 ≤ 5 分钟）
+- 回滚后确认指标恢复 + 数据一致性（OPR-G05）
+- 留痕：回滚原因/时间/操作人/结果
 
-3. **业务指标**
-   - 核心业务流程（下单/支付/登录）成功率不得下降
-   - 数据一致性校验必须在上线后执行
+## 发布后验证
 
-4. **回滚触发条件**
-   - 错误率超过阈值 → 自动回滚
-   - 业务流程完全中断 → 立即回滚
-   - 数据不一致 → 暂停发布 + 人工评估
+- 数据一致性校验 SQL 全过（OPR-G05）
+- 核心业务流程线上复验（非只看监控）
+- 确认无遗留告警
 
-### 验收项
+## 禁止
 
-- [AC-01] 监控面板已就绪
-- [AC-02] 告警阈值已配置
-- [AC-03] 回滚触发条件已定义
-- [AC-04] 观察窗口期已设定（至少 30 分钟）
+- 无回滚方案就上线（违规）
+- 全量直上无灰度（违规，除非低风险配置变更且说明）
+- 指标异常不回滚硬扛（违规）
+- 回滚方案没演练过（违规，OPR-G04）

package/templates/operate//345/217/221/345/270/203/350/257/264/346/230/216.md

@@ -22,6 +22,9 @@ extra:
 
 # 发布说明
 
+> **产物定位**：operate 阶段产出。记录发布内容/影响/验证/回滚，是上线可追溯的凭证。
+> **核心纪律**：任何上线变更必须有回滚方案（[[开发者宪法]]）；发布说明须含回滚章节（operate-gate RELNOTE-STRUCT 守护）。
+
 ## 1. 版本信息
 - 版本号：
 - 发布日期：

package/templates/operate//351/203/250/347/275/262/351/205/215/347/275/256.md

@@ -0,0 +1,83 @@
+---
+id: ka-artifact-部署配置
+kind: artifact
+title: 部署配置
+sync_policy: copy_to_project
+status: active
+extra:
+  name: deploy-config
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  type: artifact
+  domain: operate
+  stage: operate
+  owner_mechanism: mc-generic-artifact
+---
+
+# 部署配置
+
+> **产物定位**：operate 阶段必出。把环境、依赖、部署方式、健康检查、回滚定清楚。
+> **核心纪律**：部署可回滚（[[开发者宪法]]）；配置走环境变量不硬编码（[[安全加固]]）。
+> **完成判定**：见文末。
+
+## 1. 环境规划
+| 环境 | 用途 | 访问范围 | 数据来源 | 配置差异 |
+|------|------|---------|---------|---------|
+| 开发 | | | | |
+| 测试 | | | | |
+| 预发 | | | | |
+| 生产 | | | | |
+
+## 2. 环境变量与密钥
+| 变量名 | 用途 | 是否敏感 | 默认值 | 各环境取值来源 |
+|--------|------|---------|--------|--------------|
+
+> 敏感变量必须走密钥管理/环境变量注入，禁止写入镜像或代码（shared-gate SEC-02）。
+
+## 3. 依赖服务
+| 服务 | 用途 | 版本 | 访问方式 | SLA/可用性要求 | 失败降级 |
+|------|------|------|---------|--------------|---------|
+| 数据库 | | | | | |
+| 缓存 | | | | | |
+| 消息队列 | | | | | |
+
+## 4. 部署方式
+- 部署形态：Docker / k8s / 裸机 / Serverless
+- 镜像/制品来源：
+- 部署流程：构建 → 推送 → 拉起 → 健康检查 → 放量
+
+## 5. 健康检查与资源
+| 项 | 配置 |
+|----|------|
+| 健康检查端点 | |
+| 就绪检查 | |
+| 存活检查 | |
+| CPU/内存限制 | |
+| 副本数/扩缩容策略 | |
+
+## 6. 监控告警
+| 指标 | 告警阈值 | 处理动作 |
+|------|---------|---------|
+| 错误率 | | |
+| P99 延迟 | | |
+| 资源使用率 | | |
+
+## 7. 回滚方案（必填）
+| 场景 | 回滚方式 | 回滚耗时 | 验证方法 | 触发条件 |
+|------|---------|---------|---------|---------|
+
+> operate-gate OPR-G04：回滚预案须在预发演练，总耗时 ≤ 5 分钟。
+
+## 完成判定
+
+- [ ] 四环境规划完整（开发/测试/预发/生产）
+- [ ] 敏感变量标注并走密钥管理（无硬编码）
+- [ ] 依赖服务列出失败降级
+- [ ] 健康检查（就绪+存活）配置
+- [ ] 监控告警覆盖错误率/延迟/资源
+- [ ] 回滚方案有且可演练

package/templates/shared/enforced.md

@@ -2,17 +2,21 @@
 id: shared-enforced
 kind: enforced
 gate: shared-gate
-title: 跨阶段通用强制检查清单
+title: 共享硬底线
 sync_policy: engine_only
 status: active
+extra:
+  owner_mechanism: mc-stage-gate-engine
 checks:
+  # —— SoloForge 自身架构边界（守护引擎不被污染）——
   - id: SHD-LLM01
     executor: regex_pattern_scan
     rule: "SoloForge 源码禁止直接调用 LLM API（架构边界：编排引擎不绑定模型，产出上限由客户端 AI 决定）"
     severity: error
     check_type: deterministic
     pattern: '/(?:anthropic|openai)\.(?:messages|chat)\.(?:create|completions)|new\s+Anthropic\(|new\s+OpenAI\(/'
-    languages: [通用]
+    languages:
+      - 通用
     evidence_required:
       - "regex_pattern_scan 扫描结果（src/ 无 LLM API 直接调用命中）"
     gate: shared-gate
@@ -23,13 +27,50 @@ checks:
     severity: warning
     check_type: deterministic
     pattern: '/throw\s+new\s+Error\(\s*"[A-Za-z]/'
-    languages: [ts, 通用]
+    languages:
+      - ts
+      - 通用
     evidence_required:
       - "regex_pattern_scan 扫描结果（src/ 无英文 throw Error/日志）"
     gate: shared-gate
     target: self
+  # —— 用户项目代码安全底线 ——
+  - id: SEC-01
+    executor: regex_pattern_scan
+    rule: "禁止提交私钥内容（含 BEGIN PRIVATE KEY 头）"
+    severity: error
+    check_type: deterministic
+    pattern: '/-----BEGIN (RSA |EC |DSA |OPENSSH |)PRIVATE KEY-----/'
+    languages:
+      - 通用
+    evidence_required:
+      - "regex_pattern_scan 扫描结果（git diff 变更文件无私钥泄露）"
+    gate: shared-gate
+    target: self
+  - id: SEC-02
+    executor: regex_pattern_scan
+    rule: "禁止硬编码高熵密钥/密码（password/secret/api_key/token 赋值字面量）"
+    severity: warning
+    check_type: deterministic
+    pattern: "/(password|passwd|secret|api[_-]?key|access[_-]?key|private[_-]?key|auth[_-]?token)\\s*[:=]\\s*[\"'][^\"'\\s]{12,}/i"
+    languages:
+      - 通用
+    evidence_required:
+      - "regex_pattern_scan 扫描结果（命中须确认是否测试 fixture/文档示例，真实密钥必须改走环境变量或密钥管理）"
+    gate: shared-gate
+    target: self
 ---
 
-# shared-gate 跨阶段通用强制检查清单
+# shared-gate 共享硬底线
+
+跨所有阶段、不可商量的底线。`gate_registry_bridge` 从此文件聚合到 shared-gate。分两类：
+
+**SoloForge 自身架构边界**（守护引擎源码不被污染）：
+- `SHD-LLM01`：源码不直接调 LLM（error）—— 编排引擎不绑定模型
+- `SHD-COMMENT01`：源码错误/日志中文（warning）
+
+**用户项目代码安全底线**：
+- `SEC-01`：私钥泄露（error，高确定性零误报）
+- `SEC-02`：硬编码密钥（warning，可能误报测试 fixture，命中后人工确认）
 
-跨阶段通用强制规则（所有研发阶段都适用，由 shared-gate 聚合）。
+> 各域代码质量门禁（中文注释/无空 catch/类型安全/Controller 不含业务逻辑等）见对应域 enforced；路径穿越写入由运行时 scope_controller 强制，不在此重复。

package/templates/shared//345/217/215/351/246/210/344/277/256/345/244/215/351/227/255/347/216/257.md

@@ -0,0 +1,86 @@
+---
+id: ka-guidance-反馈修复闭环
+kind: guidance
+title: 反馈修复闭环
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 验证失败
+  - 门禁失败
+  - 检查失败
+  - 修复
+  - fix
+  - 重试
+  - retry
+  - escalate
+  - 反馈
+  - 复验
+  - 修复闭环
+  - gate
+  - 复检
+extra:
+  name: feedback-repair-loop
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: procedure
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-verifier
+---
+
+# 反馈修复闭环：报错怎么修、修完怎么回来
+
+> verify/gate 失败后，按本流程闭环。禁止假修复、禁止跳过。
+> 这是把引擎 Reflexion 机制翻译成可执行步骤。
+
+## 第一步：读懂门禁反馈
+
+verify 失败后，引擎把上次失败的 findings 注入回来。每条 finding 含：
+- `id`：检查项编号（如 ARC-01、SEC-01）
+- `severity`：`error`（必须修）/ `warning`（应当修）/ `info`（advisory 参考）
+- `message`：技术原因（为什么失败）
+- `evidence_required`：补什么证据才算修好
+
+还有一段大白话 `recovery_summary`：整体怎么了、该干什么、有什么 pending 项。
+
+## 第二步：逐条修复（按 severity 分流）
+
+**error 级**（必须全修）：
+1. 看 message 定位根因，不是只看表象（[[工程执行总纲]] 思考先行）
+2. 按 evidence_required 补齐证据
+3. 修复限于同一限界上下文；跨越无关模块必须回到任务拆解
+
+**warning 级**（尽量修）：
+- 影响小可记录风险后放行，但在交付说明里写清放行理由
+
+**info 级（semantic）**：
+- advisory 不阻断，但是给客户端 AI 的评判参考
+- 必须认真评估，不能当没看见；评估结论写进交付说明
+
+## 第三步：修完回到哪一步重验
+
+- 修复的是哪个阶段的产物，就回那个阶段用 `sf_work action=verify` 重验
+- 引擎有 `pending_return` 机制：补产后 verify 通过，可恢复到原域继续推进
+- 不要跨阶段乱跳（跳转受白名单约束）
+
+## 第四步：重试与 escalate
+
+- 最多重试 5 次
+- 5 次仍失败 → escalate，转人工，不要硬撑硬绕
+
+## 禁止
+
+- 假修复（改了但没解决根因，下次还报）
+- 删断言/降覆盖率/加无关 mock 让门禁过（[[工程执行总纲]] 精准修改的硬失败）
+- 隐藏失败 finding
+- 把 advisory 结果当成 required 通过
+- 没有重验就标记完成
+
+## 证据要求
+
+修复后必须给出：改了什么、对应哪条 finding、重验结果（命令 + 输出）。不接受「已修复」三字。

package/templates/shared//345/267/245/347/250/213/346/211/247/350/241/214/346/200/273/347/272/262.md

@@ -0,0 +1,148 @@
+---
+id: ka-guidance-工程执行总纲
+kind: guidance
+title: 工程执行总纲
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 实现
+  - 编码
+  - 开发
+  - 重构
+  - 写代码
+  - 改bug
+  - 修复
+  - 设计
+  - 测试
+  - 验证
+  - 架构
+  - 部署
+  - 需求
+  - 排查
+  - 联调
+  - 改造
+  - 迁移
+extra:
+  name: engineering-execution-charter
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: constraint
+  lifecycle_status: active
+  version: 2.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-core-engineering-principles
+---
+
+# 工程执行总纲
+
+> 所有阶段（需求→设计→实现→测试）的元规则。资深工程师干活的四条硬原则。
+> 每条都要证据证明，不接受 AI 自述。
+
+## 四条原则
+
+### 一、思考先行（Think Before Coding）
+
+编码前先明确：问题是什么、目标是什么、输入和约束是什么、哪里不确定。不假设、不隐藏困惑、不把模糊需求直接转成代码。
+
+必须做到：
+- 区分「可推断事实」「假设」「需要用户确认的问题」
+- 只问最小阻塞问题，不把非阻塞细节抛给用户
+- 把不确定项记录为 assumption，不得假装确定
+
+硬失败（命中即停）：
+- 缺必要输入却开始写代码
+- 写入范围不明确却修改文件
+- 外部副作用权限不明确却执行命令
+- 把未知事实写成确定结论
+
+不确定性分级：
+- `blocking`：不问不能继续（写入路径、业务口径、破坏性操作）
+- `material`：可先推进，但必须记录假设和风险
+- `minor`：可合理默认，但在结果里说明
+
+### 二、简单优先（Simplicity First）
+
+用最少代码、最少抽象、最少新增文件解决已确认目标。不为未确认的未来需求提前设计。
+
+必须做到：
+- 最少代码解决问题
+- 引入新抽象/依赖/模块时说明必要性
+- 不为简单 CRUD 强行套复杂模型
+
+硬失败：
+- 为局部问题引入无必要新依赖
+- 为简单修复新增大范围架构层
+- 没有目标支撑却扩展公共 API/配置
+
+「简单」不是少做：
+- 不写测试不叫简单
+- 不接主链路不叫简单
+- 不处理边界/不做错误处理不叫简单
+
+### 三、精准修改（Surgical Changes）
+
+只改必须改的。不顺便重构、不无关格式化、不扩大范围、不污染用户已有改动。
+
+必须做到：
+- 只改必要文件、必要行、必要行为
+- 遇到用户已有修改必须保护，不得回滚
+
+硬失败：
+- 改范围外文件
+- 改与目标无关的行为
+- 未经确认回滚用户已有改动
+- 大范围格式化掩盖真实变更
+- 为让测试过而删断言/降覆盖率/加无关 mock
+
+允许的必要联动：
+- 主链路接入必须改入口文件
+- 类型变化必须改调用方
+- schema 变化必须改 model/query/API
+- contract 状态变化必须改 registry/测试
+
+### 四、目标驱动（Goal-Driven）
+
+先定可验证目标，再执行；执行后必须验证；失败要修并重验，直到通过或明确阻塞。
+
+必须做到：
+- 明确目标和验收标准
+- 禁止「功能正常」「看起来没问题」等模糊成功标准
+- 输出未验证项和人工确认项
+
+硬失败：
+- 没有可验证目标就开始实现
+- 未执行验证却输出「全部通过」
+- 验证失败仍标记完成
+- 隐藏未验证项
+
+## 冲突优先级
+
+原则冲突时按此裁决：
+
+```
+安全/权限/隐私 > 目标驱动 > 思考先行 > 精准修改 > 简单优先
+```
+
+- 不能为了简单牺牲验证
+- 不能为了少改而不接主链路
+- 不能为了快而隐藏阻塞不确定性
+- 必要验证、必要入口接入、必要错误处理 优先于「少写代码」
+
+## 反规避（核心）
+
+四原则必须由证据证明，AI 自述无效。
+
+伪满足示例（都是违规）：
+- 说「已思考清楚」但没有输入/假设/目标证据
+- 说「保持简单」但实际新增大抽象
+- 说「只改必要文件」但 diff 有无关变更
+- 说「验证通过」但没有真实证据
+- 把未执行验证写成「建议验证」后仍标记完成
+- 把用户没确认的业务口径写成事实
+
+自述不能代替：澄清记录 / 假设记录 / 目标定义 / 验证证据。
+required 原则失败不能进入 completed。

package/templates/shared//345/267/245/347/250/213/347/272/252/345/276/213.md

@@ -0,0 +1,71 @@
+---
+id: ka-guidance-工程纪律
+kind: guidance
+title: 工程纪律
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 命名
+  - 注释
+  - 职责
+  - 错误处理
+  - 异常
+  - 日志
+  - 代码风格
+  - 实现
+  - 编码
+  - 写代码
+extra:
+  name: engineering-discipline
+  scope:
+    - '*'
+  products:
+    - '*'
+  type: constraint
+  lifecycle_status: active
+  version: 1.0.0
+  last_reviewed: '2026-06-17'
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-detail-discipline
+---
+
+# 工程纪律（基本功）
+
+> 合并命名/注释/单一职责/错误处理/日志的基本要求。这是代码质量的底线。
+> 吸收旧的「工程纪律」「细节纪律」「通用机械条款」「代码注释与日志契约」「命名」等碎拆文件。
+
+## 命名
+
+- 表达真实含义，禁止含糊/误导/过度缩写/无意义命名
+- 好命名让人少看注释也能懂
+- 命名和行为必须一致（叫 validate 就真的校验，别混着干别的）
+
+## 注释
+
+- 解释**为什么**这样做、业务约束、历史原因、边界、风险
+- 不复述代码（`// 给 i 加 1` 是废话）
+- 代码注释、日志消息、用户可见错误提示一律简体中文，技术术语/标识符保留原文
+
+## 单一职责
+
+- 一个函数只做一类事
+- 一个函数同时做参数校验+权限判断+数据查询+状态计算+写入+发消息+记日志 → 拆分
+- 单文件/单类职责清晰，避免上帝对象（>20 字段考虑拆分聚合根）
+
+## 错误处理
+
+- 禁止空 catch（至少记日志，不得静默吞异常）
+- 错误信息说清楚：哪步失败、关键参数、可能原因、下一步怎么做
+- 用户可见错误用中文；日志用中文，标识符保留原文
+
+## 日志
+
+- 统一走 logger（`userInfo`/`userWarn`/`userError`/`debug`/`internalWarn`），禁止 `console.log/error/warn` 直接调用
+- 关键路径有可观测日志，便于排查
+- 敏感信息不得进日志（密钥、token、个人隐私）
+
+## 数据写入边界
+
+- 不得向 `.soloforge/tasks/`、`.env`、`.git/`、`node_modules/` 写入（安全底线）
+- 写文件用原子写，避免半写状态