soloforge 1.1.45 → 1.1.47

package/templates/shared//346/250/241/347/211/210/350/264/241/347/214/256/346/214/207/345/215/227.md

@@ -1,282 +0,0 @@
----
-id: 模版贡献指南
-kind: guidance
-title: 模版贡献指南
-sync_policy: engine_only
-status: active
-triggers:
-  - 新增模版文件、模版贡献、模版资产维护
-extra:
-  name: template-contribution-guide
-  type: constraint
-  lifecycle_status: active
-  scope:
-    - '*'
-  domain:
-    - '*'
-  stage: _global
-  owner_mechanism: mc-standard-asset-contract
----
-
-# 模版贡献指南
-
-向 `templates/` 新增一个能被 SoloForge 正确路由、消费、验证的模版资产，需要完成四件事：**放对目录 → 填对 frontmatter → 注册到代码 → 本地验证**。本指南按这个顺序展开，每一步都给出真实可操作的规则。
-
-> **字段合法值权威来源**：`type` / `scope` / `domain` 等字段的完整合法值清单详见 `templates/internal/rules/模版Frontmatter.md`。**目录归属与代码注册机制以本指南为准**（规范文档的目录分区描述已滞后于实际磁盘结构）。
-
----
-
-## 一、资产类型与目录归属
-
-SoloForge 的 `.md` 模版资产分 9 种 `type`，每种落在固定目录。`scaffolds/`（`.hbs`）和 `profiles/`（`.yaml`）不属于 `.md` 资产体系，由对应引擎直接消费，**无 frontmatter、无需注册**。
-
-| `type` | 目录 | 职责 |
-|--------|------|------|
-| `pattern` | `patterns/` | 用户编码规范 / 设计模式 |
-| `procedure` / `pipeline_procedure` | `procedures/` | 开发流程 / 管线工作流 |
-| `artifact_template` / `acceptance_template` | `artifacts/domain/...` | 产出物模版 / 验收交付模版 |
-| `review_rule` | `rules/domain/...` | 审查 / 校验规则 |
-| `governance_rule` | `internal/rules/` | 引擎治理硬规则 |
-| `pattern`（运行时） | `internal/patterns/` | 引擎运行时模式 |
-| `domain` | `domain/` | 领域知识 |
-| `checklist` | `checklists/` | 验收清单（打勾式） |
-| —（YAML 配置） | `gates/domain/*.yaml` | 阶段门控配置（独立格式） |
-| —（`.hbs`） | `scaffolds/{react,spring-boot}/` | 代码脚手架（无 frontmatter） |
-| —（`.yaml`） | `profiles/` | 产品配置（无 frontmatter） |
-
-### 二级分区：按能力域（不是系统类型）
-
-`artifacts/`、`rules/`、`gates/` 在 `domain/` 下按**能力域**二级分区。这是当前磁盘的真实结构：
-
-```text
-artifacts/domain/{brownfield, build, design, operate, verify}/
-rules/domain/   {build, design, operate, shared, verify}/
-gates/domain/   {build,design,operate,slice,verify}-gate.yaml   （平铺）
-```
-
-- `build` / `design` / `operate` / `verify` — 对应 4 能力域的通用产物
-- `brownfield`（仅 `artifacts/`）— 老系统改造专用产物（回滚、兼容、数据清洗等）
-- `shared`（仅 `rules/`）— 跨域能力复用的审查规则（如 SOLID）
-
-> 其余目录（`patterns/`、`procedures/`、`internal/`、`domain/`、`checklists/`）**平铺，无二级分区**。
-
-### 验收文件归属
-
-| 内容形态 | 放哪 | `type` |
-|---------|------|--------|
-| 打勾式清单（AI 做校验） | `checklists/` | `checklist` |
-| 产出物格式模版（AI 按模版输出制品） | `artifacts/domain/<域>/` | `artifact_template` |
-
-同名主题只能二选一。
-
----
-
-## 二、命名规范
-
-1. **用字统一**：文件名和正文一律使用「模版」（本仓库标准用字，禁用简体写法）。
-2. **`procedures/` 后缀**（按语义区分）：
-   - `…流程` — 标准执行流程（功能开发、调试排查）
-   - `…工作流` — 管线直接调度的工作流（架构设计、OOD 设计）
-   - `…流水线` — 自动化多步骤（安全加固、数据迁移）
-3. **机制 ID**：`mc-` 前缀 + kebab-case，按主题分组：
-   - `mc-engine-runtime`（internal/patterns）、`mc-backend-pattern` / `mc-frontend-pattern` / `mc-infra-pattern` / `mc-general-pattern`（patterns/）
-   - `mc-domain-knowledge`（domain/）、`mc-generic-artifact` / `mc-existing-system-artifact`（artifacts/）
-   - `mc-generic-review` / `mc-existing-system-review` / `mc-new-system-review`（rules/）、`mc-checklist`（checklists/）
-
----
-
-## 三、Frontmatter 字段
-
-### 必填（缺一不可，由 `template_frontmatter_compliance.test.ts` 强制）
-
-```yaml
----
-name: ood-design-summary              # kebab-case 英文标识
-type: artifact_template               # 见第一节 9 种合法值
-scope:                                # 技术栈适用范围
-  - backend
-  - frontend
-domain: "build"                       # 能力域；procedure/pipeline_procedure 必填具体域
-lifecycle_status: active              # active | deprecated | draft
-owner_mechanism_id: mc-ood-solid-contract
-verification_layer: L2                # 校验层（必填）：内置模板资产统一 L2（注入审查）；项目自建 L0/L1 确定性探针规则见 docs/项目规则分层写法.md
----
-```
-
-### 常用选填
-
-| 字段 | 说明 |
-|------|------|
-| `triggers` | 触发关键词数组，辅助知识匹配（替代旧 `when` / `primary_triggers`）。写宽些，含中英文同义词 |
-| `authority` | `canonical`（仅 `internal/rules/`、`rules/domain/shared/` 允许）/ `supporting`（默认） |
-| `products` | 产品类型，当前全部 `['*']` |
-| `id` | 资产稳定标识，惯例 `ka-{type}-{中文名}`，如 `ka-artifact_template-OOD设计摘要模版` |
-| `priority` | `P0` / `P1`（P0 关键资产才进 ASSET_MANIFEST，见第四节） |
-| `consumes` / `emits` / `consumed_by` / `required_evidence` | 机制间依赖链；同簇内 `emits` 与 `required_evidence` 值匹配可自动推断 `consumes` |
-| `companions` / `requires_context` | **仅 artifact 模版**：配套规则与软知识 `companions: { rules: [文件名:usage], guides: [文件名] }`（usage ∈ execute/review/check）/ 上下文引擎视图 |
-| `version` / `last_reviewed` | 元数据，便于追溯 |
-
-> 精确路由类型（`procedure` / `pipeline_procedure`）必须声明**具体** `domain`，不能省略或写 `["*"]`——确保按域精确路由（由合规测试第 4 条守护）。`pattern` / `checklist` / `domain` 等通用类型可省略 `domain` 表示全域适用。
-
-### 完整示例
-
-**artifact 模版**（`artifacts/domain/build/OOD设计摘要.md`）：
-
-```yaml
----
-name: ood-design-summary
-type: acceptance_template
-scope: [backend, frontend]
-domain: "build"
-lifecycle_status: active
-authority: supporting
-owner_mechanism_id: mc-ood-solid-contract
-priority: P1
-id: ka-artifact_template-OOD设计摘要模版
-triggers: ["面向对象设计", "SOLID", "复杂业务实现"]
-consumes: [mc-ood-solid-contract]
-emits: [acceptance_report]
-required_evidence: [ood_design_summary, code_review_findings]
-requires_context: []
-version: 1.1.0
-last_reviewed: '2026-06-01'
----
-```
-
-**编码规范**（`patterns/SOLID设计.md`）：`type: pattern`、`domain: "verify"`、`authority: supporting`。
-
-**验收清单**（`checklists/验证.md`）：`type: checklist`、`domain: "verify"`、`emits: []`。
-
----
-
-## 四、注册到代码（让系统认得）
-
-光建 `.md` 文件不够，必须在代码注册表登记一条 entry，否则资产不会被消费（`template_consumption_coverage.test.ts` 会报红）。
-
-### 4.1 普通资产 → `explicit_asset_registry`
-
-在 `src/domain/asset_registry/explicit_asset_registry/` 下**按类型分组的文件**里加一条。分组文件命名见下表，照类型对号入座：
-
-| 资产类型 | 分组文件 |
-|---------|---------|
-| `pattern` | `patterns_part1.ts` / `patterns_part2.ts` / `patterns_part3.ts` |
-| `procedure` / `pipeline_procedure` | `procedures_part1.ts` / `procedures_part2.ts` |
-| `artifact_template`（通用） | `artifacts_shared_part1.ts` / `artifacts_shared_part2.ts` |
-| `artifact_template`（老系统） | `artifacts_existing_system.ts` |
-| `review_rule`（通用） | `rules_shared.ts` |
-| `review_rule`（管线） | `rules_pipeline.ts` |
-| `governance_rule` | `internal_rules_part1.ts` / `internal_rules_part2.ts` |
-| `pattern`（运行时） | `internal_patterns.ts` |
-| `checklist` / `domain` / `gates` / `scaffolds` / `profiles` | 同名文件 |
-
-**entry 写法**（以本指南自身的注册 `contributing.ts` 为范例）：
-
-```ts
-export const contributing_entries: Readonly<Record<string, ExplicitAssetEntry>> = {
-  "templates/模版贡献.md": {
-    applicable_stages: ["*"],
-    asset_kind: "governance_rule",        // 值与 frontmatter 的 type 一致（注意代码层键名是 asset_kind）
-    owner_mechanism_id: "mc-standard-asset-contract",
-    asset_visibility: "soloforge_internal",  // 见第五节
-    sync_to_user_project: false,
-    sync_target: "none",
-    runtime_visibility: "index_only",
-    evidence_role: "template_guidance",
-    user_visible: true,
-    applicable_tech_stack: [] as const,
-    lifecycle_status: "active",
-    consume_category: "copy_only_pipeline",
-    mainline_consumer: "",
-    validation_entrypoint: "template_mechanism_auditor",
-  },
-};
-```
-
-> ⚠️ **术语陷阱**：代码注册结构体用 `asset_kind` 键名，frontmatter 用 `type` 键名——两者**值相同**（如都写 `governance_rule`），但键名不同，别混淆。
-
-### 4.2 P0 关键资产 → 额外进 ASSET_MANIFEST
-
-只有 `priority: P0`、需双层机制守护（模版层 + 代码层）的关键资产，才额外登记到 `src/context/templates/asset_manifest.ts` 的 `ASSET_MANIFEST`。
-
-典型 P0 资产（命令路由、工作流契约、知识注入边界、工具调用、验证、防孤岛、主链路、隐私、命令执行等）还需声明 `enforcement_status` / `layer_status` / `consumption_mode`。
-
-**普通贡献无需进 ASSET_MANIFEST**。
-
----
-
-## 五、可见性：你的资产会同步到哪里
-
-每个资产必须声明 `asset_visibility`，决定它**是否同步到用户项目、运行时是否注入 AI prompt**。选错会导致内部术语泄露或资产不生效。
-
-| `asset_visibility` | 同步到用户项目 | 运行时 | 典型资产 |
-|--------------------|:------------:|--------|---------|
-| `user_project` | ✅ | 注入 prompt | 用户可见的编码规范、领域知识、产出物模版 |
-| `global_pattern` | ✅（global_patterns） | 仅索引 | 可复用全局模式 |
-| `soloforge_internal` | ❌ | 引擎内部 | 引擎治理硬规则、运行时模式（本指南属此类） |
-| `scaffold_only` | ❌ | 脚手架消费 | `.hbs` 脚手架 |
-| `adapter_runtime_only` | ❌ | 适配器运行时 | 适配器配置 |
-
-### 内部术语保护（重要）
-
-`user_project` / `global_pattern` 资产的正文**不得含内部术语**（如 `Batch6`、`SoloForge Audit: PASS`、`Mechanism Contract Registry` 等）——这些是引擎内部概念，泄露到用户项目会造成困惑。
-
-`template_asset_visibility.test.ts` 的 `scanInternalTerms` 会扫描拦截。
-
-> 拿不准可见性？默认 `user_project`（用户可见）。引擎内部规则才用 `soloforge_internal`。
-
----
-
-## 六、本地验证
-
-提交前依次跑，全绿才算合格：
-
-```bash
-# 1. frontmatter 合规（12 条规则：type/scope/domain/authority/lifecycle_status/owner_mechanism_id 等）
-npx vitest run tests/architecture/template_frontmatter_compliance.test.ts
-
-# 2. 消费覆盖率（新资产必须被注册且能被主链路消费）
-npx vitest run tests/architecture/template_consumption_coverage.test.ts
-
-# 3. 内容格式（正文规范、无禁止结构）
-npx vitest run tests/architecture/template_content_format.test.ts
-
-# 4. 可见性与内部术语保护
-npx vitest run tests/engine/template_asset_visibility.test.ts
-
-# 5. 枚举一致性（type 等 frontmatter 枚举与代码定义对齐）
-npm run check:schema-enum
-
-# 6. 全量（兜底）
-npm test
-```
-
-发布前维护者还会跑 `npm run validate-release`（15 phase 门禁，其中 phase 8（模版卫生与项目知识消费）、phase 14（模版消费覆盖率）直接守护模版资产）。
-
----
-
-## 七、禁止字段（旧术语，不得出现在新文件）
-
-以下字段已废弃，存量文件逐步清理（由合规测试 + 纯C重构守护）：
-
-| 禁止字段 | 替代 |
-|---------|------|
-| `asset_kind`（frontmatter 层） | `type`（代码注册层仍用 `asset_kind` 键名，见第四节） |
-| `when` / `primary_triggers` / `secondary_triggers` / `negative_triggers` | `triggers` |
-| `stages`（旧 8 阶段） | `domain`（4 能力域） |
-| `routes` | `domain`（域约束统一用 `domain`） |
-| `status` | `lifecycle_status` |
-| `specificity` / `migration_note` / `artifact_schema` / `process_rules` / `forbidden_gaps` | 已迁移或删除 |
-
----
-
-## 八、PR 清单
-
-提交 PR 前自查：
-
-- [ ] 文件放在第一节对应的目录（`artifacts/rules/gates` 注意 `domain/` 能力域分区）
-- [ ] 文件名用字统一为「模版」；`procedures/` 后缀符合语义
-- [ ] frontmatter 必填字段齐全（`name` / `type` / `scope` / `domain` / `lifecycle_status` / `owner_mechanism_id`）
-- [ ] 无第七节禁止字段
-- [ ] 在 `explicit_asset_registry` 对应分组文件登记了 entry，`asset_kind` 值与 `type` 一致
-- [ ] `asset_visibility` 选对；`user_project` 资产正文无内部术语
-- [ ] 第六节 6 条验证全绿

package/templates/shared//346/250/241/347/211/210/350/265/204/344/272/247/345/217/257/350/247/201/346/200/247.md

@@ -1,48 +0,0 @@
----
-id: ka-hard-rule-模版资产可见性规则
-kind: guidance
-title: 模版资产可见性
-owner_mechanism: mc-template-asset-visibility
-sync_policy: internal
-status: active
-extra:
-  name: template-asset-visibility
-  scope:
-    - '*'
-  products:
-    - '*'
-  type: constraint
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  verification_layer: L2
-  stage: _global
----
-
-# 模版资产可见性规则
-
-## 适用范围
-
-所有 `templates/**` 资产的同步、索引、注入和消费入口。
-
-## 可见性分类
-
-| 可见性 | 说明 |
-|--------|------|
-| user_project | 用户项目知识，可同步到 `.soloforge/knowledge` |
-| soloforge_internal | SoloForge 内部治理，不进入用户项目 |
-| adapter_runtime_only | 仅 adapter 运行时消费，不进入用户知识库 |
-| scaffold_only | 仅脚手架机制消费，不进入知识索引 |
-| global_pattern | 全局工程模式，进入 `~/.soloforge/patterns` |
-
-## 硬规则
-
-- 内部资产不得同步到用户项目。
-- 不同技术栈的审查规则不得互相注入。
-- 脚手架模版只由脚手架机制消费。
-- 全局 patterns 只能作为 `template_guidance`，不得支撑项目事实。
-- 用户可见资产不得包含内部施工术语。
-
-## 术语污染扫描
-
-用户可见资产禁止出现: Batch、validate-release、SoloForge Audit: PASS、Mechanism Contract Registry 等内部术语。

package/templates/shared//346/262/273/347/220/206/350/277/220/350/241/214/346/227/266/345/276/252/347/216/257.md

@@ -1,56 +0,0 @@
----
-id: ka-pattern-governance_runtime_loop
-kind: knowledge
-title: 治理运行时循环
-sync_policy: internal
-status: active
-extra:
-  name: governance_runtime_loop
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  verification_layer: L2
-  stage: _global
-  owner_mechanism: mc-engine-runtime
----
-
-## 决策规则
-
-- 治理闭环: sample → escape → report → capability_update
-- 抽检使用风险加权抽样，critical 风险 100% 抽中
-- 逃逸报告记录发现的问题，不自动降级
-- 治理报告汇总全局状态，只读不改
-- 能力状态更新必须经 治理运行时 + 人工确认
-
-## 验收项
-
-- [AC-01] 抽检→逃逸→报告闭环测试通过
-- [AC-02] 无自动降级行为
-- [AC-03] 状态更新需人工确认
-- [AC-04] report 数据与实际 escape 一致
-
-## 何时使用
-
-advisory: 治理闭环只读不改，状态更新必须经 治理运行时 + 人工确认
-
-## 是否 hard block
-
-否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
-
-## 证据要求
-
-- 抽检→逃逸→报告→显式更新闭环测试通过
-- MCP handler 闭环测试通过
-- 无自动降级行为
--
-
-## 人工确认/降级边界
-
-- 此能力可被开发者决策覆盖
-- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
-- 降级/禁用需经 治理运行时 + 人工确认

package/templates/shared//346/263/250/345/206/214/350/241/250/345/237/272/347/241/200/350/256/276/346/226/275.md

@@ -1,49 +0,0 @@
----
-id: ka-hard-rule-注册表基础设施规则
-kind: guidance
-title: 注册表基础设施
-sync_policy: internal
-status: active
-triggers:
-  - 注册表基础设施规则
-extra:
-  name: registry-infrastructure
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: constraint
-  verification_layer: L2
-  stage: _global
-  owner_mechanism: mc-registry-infrastructure
----
-
-# 注册表基础设施规则
-
-## 核心原则
-
-注册表是 SoloForge 契约体系的基础设施层。所有机制必须通过注册表发现、验证和追踪其契约和资产。
-
-## 规则
-
-1. **注册完整性**: 每个机制必须在 MechanismContractRegistry 注册，包含 id、status、priority
-2. **资产可发现**: 所有可消费模版资产必须在 ConsumableAssetRegistry 注册，包含 path、consumption_mode、owner_mechanism_id
-3. **生命周期测试**: 每个注册表条目必须有对应的生命周期测试，验证注册/查询/状态变更
-4. **跨注册表一致性**: owner_mechanism_id 必须在 DualLayerMechanismRegistry 中存在对应条目
-5. **注册表健康检查**: validate-mechanisms 和 audit-template-mechanisms 必须能检测注册表不一致
-
-## 失败模式
-
-- 注册表条目无对应测试 → 应补充 lifecycle test
-- owner_mechanism_id 指向不存在的机制 → 应修复引用
-- 模版文件存在但未注册 → 应在 ConsumableAssetRegistry 登记
-
-## 验收标准
-
-- [ ] 所有机制契约在 registry 中可查询
-- [ ] 所有模版资产有 owner_mechanism_id
-- [ ] 注册表查询函数返回非空结果
-- [ ] validate-mechanisms 不报告注册表缺失

package/templates/shared//346/265/201/345/274/217/345/277/203/350/267/263.md

@@ -1,64 +0,0 @@
----
-id: ka-pattern-streaming_protocol
-kind: knowledge
-title: 流式心跳
-sync_policy: internal
-status: active
-extra:
-  name: streaming_protocol
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: knowledge
-  verification_layer: L2
-  stage: _global
-  owner_mechanism: mc-engine-runtime
----
-
-## 决策规则
-
-- 重型 AI 操作（tier=heavy）执行期间必须启动流式心跳
-- 心跳间隔 Heartbeat_Interval = 5000 毫秒
-- 心跳通过 stdio 输出，格式: [SoloForge Heartbeat] {操作描述} 执行中... 已耗时 {N}s，当前任务已用 {M}/{T} Token
-- 心跳包含字段: elapsed_ms, tokens_used, operation, message
-- 轻量/中型操作（light/medium）不触发心跳
-- 操作完成后调用 completeOperation() 停止心跳
-- 重型操作定义: estimated_tokens > 3000（code_generation/solution_brainstorm/verification_reasoning/review_deep_analysis）
-
-## 验收项
-
-- [AC-01] 重型操作启动后 5 秒内首次心跳输出
-- [AC-02] 心跳消息包含操作名称、耗时、Token 用量
-- [AC-03] completeOperation() 调用后心跳立即停止
-- [AC-04] 中型操作（test_generation/debug_analysis）不产生心跳
-- [AC-05] 心跳回调通过 setHeartbeatCallback() 注册
-
-## 格式规范
-
-```text
-[SoloForge Heartbeat] 代码生成 执行中... 已耗时 10s，当前任务已用 5000/30000 Token
-```
-
-## 何时使用
-
-advisory: 预算耗尽是 warning 不是 hard fail，不应阻断任务
-
-## 是否 hard block
-
-否。此能力为 advisory 状态，违规仅产生 advisory 警告，不阻断流程。
-
-## 证据要求
-
-- H1/H4 handler 测试通过
-- heartbeat 测试通过
--
-
-## 人工确认/降级边界
-
-- 此能力可被开发者决策覆盖
-- 升级到 enforced 需满足 promotion_conditions 并通过 lifecycle_test_files 测试
-- 降级/禁用需经 治理运行时 + 人工确认

package/templates/shared//346/274/224/350/277/233/345/233/236/345/275/222/351/227/250/346/216/247.md

@@ -1,50 +0,0 @@
----
-id: ka-hard-rule-演进回归门控规则
-kind: guidance
-title: 演进回归门控
-owner_mechanism: mc-evolution-regression
-sync_policy: internal
-status: active
-extra:
-  name: evolution-regression-gate
-  scope:
-    - '*'
-  products:
-    - '*'
-  type: constraint
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  verification_layer: L2
-  stage: _global
----
-
-# 演进回归门控规则
-
-## hard_rules
-
-- 新增问题 / 新增 Batch / 新机制 / 新模版 / 新测试必须经过回归门控，不得打穿既有体系。
-- 必须包含以下检查项：
-  1. 跨 Batch 总回归门：新变更不得破坏已验收的 Batch 门禁。
-  2. 模版补齐检查：新机制必须有 required 模版资产。
-  3. 机制归属检查：新模版必须归属到正确机制。
-  4. 发布门禁更新：新问题/Batch 必须更新发布门禁配置。
-  5. 旧问题反向影响检查：新变更不得使已关闭问题重新失效。
-- 重复问题必须被 DuplicateIssueCheck 检测并阻断。
-- pending 状态的问题/机制不得通过门禁。
-
-## not_done_if_missing
-
-- 新问题未经 DuplicateIssueCheck → hard fail。
-- 新增功能批次未继承既有历史回归基线 → hard fail。
-- 模版层需更新但未更新 → hard fail。
-- 新增机制无 required 模版资产 → hard fail。
-- 发布门禁配置未更新 → hard fail。
-
-## verification_evidence
-
-- `EvolutionGateResult` 包含 passed/failed 状态和检查项列表。
-- `DuplicateCheckResult` 包含重复检测结果。
-- `performEvolutionGate()` 执行全部五项检查。
-- `checkDuplicateIssue()` 检测重复问题。
-- `diagnostic_codes`: duplicate-issue, pending-gate, missing-template, batch-regression-failed。

package/templates/shared//347/224/250/346/210/267/345/217/215/351/246/210/345/245/221/347/272/246.md

@@ -1,86 +0,0 @@
----
-id: ka-hard-rule-用户反馈契约规则
-kind: guidance
-title: 用户反馈契约
-sync_policy: internal
-status: active
-triggers:
-  - 用户反馈契约规则
-extra:
-  name: user-feedback-contract
-  scope:
-    - '*'
-  products:
-    - '*'
-  lifecycle_status: active
-  version: 1.1.0
-  last_reviewed: '2026-06-01'
-  type: constraint
-  verification_layer: L2
-  stage: _global
-  owner_mechanism: mc-user-feedback
----
-
-# 用户反馈契约规则
-
-## 核心约束
-
-1. 每个工具只能输出其 `getAllowedFeedbackKinds` 允许的反馈类型。
-2. 反馈消息必须包含：kind、severity、title、summary。禁止空洞反馈。
-3. 技术内容（路径、命令、错误码）禁止翻译，必须保留原文。
-4. `blocked` 类型反馈必须包含阻塞原因和建议下一步。
-5. `failure` 类型反馈必须包含失败证据和 retry_hint。
-6. 任何用户反馈、缺陷、设计疑问或实际使用偏差，不得只按表面文件、单个目录或单个场景收窄处理。
-7. 进入修复讨论前，必须先完成全局抽象审查：
-   - 该问题属于哪个机制族？
-   - 是否只是某个现象暴露出来的系统性问题？
-   - 是否同时影响 SoloForge 自身与用户项目使用路径？
-   - 是否涉及模版层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归？
-   - 是否需要抽象成通用能力，而不是只修当前案例？
-8. 如果全局抽象审查未完成，只能输出待分析项、影响矩阵和建议讨论顺序，不得直接给单点修复结论。
-9. 如果当前案例只是系统性问题的一个样本，修复方案必须覆盖同类入口、同类资产、同类任务和新增资产防回归。
-
-## 适用场景
-
-- 所有 SoloForge 工具的输出反馈
-- sf_gate 结果反馈
-- sf_work action=verify 学习反馈
-- sf_work action=act 降级/澄清反馈
-- 用户反馈实际使用问题
-- 讨论新增机制、模版、规则、流程、验收或发布风险
-- 将问题落入 Batch、备忘录、发布门槛或施工合同前
-
-## 违规处理
-
-- 禁止的反馈类型 → hard_fail，阻断输出
-- 空洞反馈 → advisory，标记质量降级
-- 翻译技术内容 → advisory，标记违规
-- 未做全局抽象审查就收窄为单点修复 → hard_fail，退回机制族归因
-- 只修当前文件/目录/样例但未覆盖同类路径和防回归 → hard_fail，要求补齐通用能力
-- 未分析 SoloForge 自身与用户项目双路径影响 → hard_fail，要求补齐影响矩阵
-- 未说明模版层、知识层、机制层、adapter、CLI、MCP、发布门禁、迁移和防回归影响 → hard_fail，要求补齐跨层影响
-
-## 全局抽象审查输出
-
-每次用户反馈进入讨论或施工合同前，必须形成以下结构化结论：
-
-```text
-1. 表面现象:
-2. 机制族归因:
-3. 是否系统性问题:
-4. SoloForge 自身影响:
-5. 用户项目影响:
-6. 涉及层级:
-   - 模版层:
-   - 知识层:
-   - 机制层:
-   - adapter:
-   - CLI:
-   - MCP:
-   - 发布门禁:
-   - 迁移:
-   - 防回归:
-7. 是否应抽象成通用能力:
-8. 不应只修的局部案例:
-9. 施工和验收必须覆盖的同类路径:
-```