soloforge 1.1.40 → 1.1.43

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

@@ -0,0 +1,49 @@
+---
+id: ka-hard-rule-core-experience-principle
+kind: guidance
+title: 核心体验原则
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 新增机制
+  - 新增模版
+  - 新增 workflow
+  - 发布门禁
+extra:
+  name: core-experience-principle
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  consumes:
+    - mc-plan-proposal-gate
+  priority: P0
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  hard_blocks:
+    - 机制未接主线
+    - 用户路径过长
+    - 假完成
+  required_evidence:
+    - CoreExperiencePrincipleEvaluation
+  fallback: manual_required
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-core-experience-principle
+---
+
+## 核心体验原则
+
+### 四条原则
+1. **机制强，路径短** — 机制必须接入真实主链路，用户主入口不超过一次自然语言指令或一个 CLI 命令
+2. **规则硬，体验轻** — 关键失败硬阻断，低风险任务轻量
+3. **证据足，不啰嗦** — 证据可审查，输出清晰简洁
+4. **能自动修复，不假装完成** — 失败进入 repair_reverify 或 manual_required
+
+### 禁止
+- 机制只存在于文档，不接主链路
+- 硬规则降级为 warning 后继续
+- 验证失败后标记 completed/delivered

package/templates/shared//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

@@ -0,0 +1,158 @@
+---
+id: ka-hard-rule-核心工程执行原则
+kind: guidance
+title: 核心工程执行原则
+sync_policy: copy_to_project
+status: active
+triggers:
+  - 核心工程执行原则
+extra:
+  name: core-engineering-principles
+  scope:
+    - '*'
+  products:
+    - '*'
+  lifecycle_status: active
+  authority: canonical
+  priority: P0
+  consumes:
+    - mc-all-mechanisms
+  hard_blocks:
+    - 中文策略违反
+    - 非必要英文
+  fallback: manual_required
+  required_evidence:
+    - core_principles_report
+  version: 1.1.0
+  last_reviewed: '2026-06-01'
+  type: constraint
+  verification_layer: L2
+  stage: _global
+  owner_mechanism: mc-core-engineering-principles
+---
+
+# 核心工程执行原则
+
+> 适用: 所有 code_execution / multi_stage_plan / single_artifact 路由。
+
+## 四条原则
+
+### 原则一: Think Before Coding — 编码前先思考
+
+编码前先明确问题、目标、输入、约束和不确定性。不假设、不隐藏困惑、不把模糊需求直接转成代码。
+
+**必须做到:**
+- 暴露阻塞性困惑，不假装理解
+- 区分可推断事实、假设、需要用户确认的问题
+- 只问最小阻塞问题，不把非阻塞细节抛给用户
+- 把 material 级不确定记录为 assumption，不得假装确定
+
+**硬失败条件:**
+- 缺少必要输入却开始写代码
+- 写入 scope 不明确却修改文件
+- 外部副作用权限不明确却执行命令
+- 把未知事实写成确定结论
+- 隐藏需要用户确认的业务口径
+
+**不确定性分级:**
+- `blocking`: 不问不能继续（写入路径、业务口径、外部副作用授权、破坏性操作）
+- `material`: 可先推进，但必须记录假设和风险（UI 文案偏好、非关键默认配置）
+- `minor`: 可合理默认，但在结果里说明（文件命名细节、无风险排序偏好）
+- `non_blocking`: 不打断用户，不影响当前执行
+
+### 原则二: Simplicity First — 简单优先
+
+优先用最少代码、最少抽象、最少新增文件解决已确认目标。不为了未确认的未来需求提前设计复杂结构。
+
+**必须做到:**
+- 最少代码解决问题
+- 引入新抽象、新依赖、新模块时说明必要性
+- 不为简单 CRUD 强行套复杂领域模型
+
+**硬失败条件:**
+- 为局部问题引入无必要新依赖
+- 为简单修复新增大范围架构层
+- 没有用户目标支撑却扩展公共 API/配置/registry
+- 使用复杂方案绕过已有简单本地模式
+
+**不是"少做":**
+- 不写测试不叫简单
+- 不接主链路不叫简单
+- 不处理边界不叫简单
+- 不做必要错误处理不叫简单
+- 不建必要抽象不叫简单
+
+**minimum_sufficient_solution 必须满足:**
+- 满足用户目标
+- 接入真实路径
+- 覆盖关键失败路径
+- 有验证证据
+- 没有不必要抽象/依赖/公共 API 扩张
+
+### 原则三: Surgical Changes — 精准修改
+
+只改必须改的内容，不顺便重构、不无关格式化、不扩大 scope、不污染用户已有改动。
+
+**必须做到:**
+- 只改必要文件、必要行、必要行为
+- 遇到用户已有修改时必须保护，不得回滚
+
+**硬失败条件:**
+- 修改 scope 外文件
+- 修改与目标无关的文件或行为
+- 未经确认回滚用户已有改动
+- 大范围格式化掩盖真实变更
+- 为了让测试过而删除断言、降低覆盖率、增加无关 mock
+
+**允许的必要联动修改:**
+- 主链路接入必须修改入口文件
+- 类型变化必须修改调用方
+- schema 变化必须修改 model/query/API
+- 验证失败需要修改测试或 fixture
+- contract 状态变化必须修改 registry、diagnostic、verification 和相关测试
+
+### 原则四: Goal-Driven Execution — 目标驱动执行
+
+先定义可验证目标，再执行；执行后必须验证；验证失败要修复并重新验证，直到通过或明确阻塞。
+
+**必须做到:**
+- 明确目标和验收标准
+- 禁止"功能正常""看起来没问题"等模糊成功标准；必须写出已执行验证和剩余风险
+- 输出未验证项和人工确认项
+
+**硬失败条件:**
+- 没有可验证目标就开始实现
+- 没有 VerificationPlan 就标记完成
+- 未执行验证却输出"全部通过"
+- 验证失败仍进入 completed / delivery_ready
+- 隐藏未验证项
+
+## 原则冲突优先级
+
+```text
+安全/权限/隐私 > Goal-Driven Execution > Think Before Coding > Surgical Changes > Simplicity First
+```
+
+裁决规则:
+- 不能为了简单而牺牲验证
+- 不能为了少改而不接入主链路
+- 不能为了快而隐藏阻塞性不确定性
+- 必要验证、必要入口接入、必要错误处理优先于"少写代码"
+
+## 反规避规则
+
+四原则必须由证据证明，不接受 AI 自述。
+
+伪满足示例:
+- 写一句"已思考清楚"，但没有输入、假设、目标证据
+- 说"保持简单"，但实际新增大抽象
+- 说"只改必要文件"，但 diff 里有无关变更
+- 说"验证通过"，但没有真实 evidence
+- 把未执行验证写成"建议验证"后仍标记完成
+- 把用户没确认的业务口径写成事实
+
+硬规则:
+- 自述不能代替 ClarificationNeed / AssumptionRecord / GoalDefinition / VerificationEvidence
+- required 原则失败不能进入 completed
+- 验证失败必须进入 repair_reverify 或 manual_required
+- 不能用 advisory 结果覆盖 required 失败

package/templates/shared//346/250/241/347/211/210Frontmatter.md

@@ -0,0 +1,126 @@
+---
+id: 模版Frontmatter
+kind: guidance
+title: 模版 Frontmatter 规范
+sync_policy: internal
+status: active
+triggers:
+  - 模版文件写入、frontmatter 校验、资产注册
+owner_mechanism: mc-standard-asset-contract
+---
+
+# 模版 Frontmatter 规范（归零重构版）
+
+> 权威来源：本文档定义 `templates/` 下所有 .md 资产的 frontmatter 字段合法值、必填/选填、语义。
+> 目录按研发阶段组织（design/build/verify/operate/shared），不再按资产类型分目录。
+
+---
+
+## 一、字段体系
+
+### 1.1 核心字段（所有 kind 共有，必填）
+
+| 字段 | 必填 | 合法值 | 说明 |
+|------|:---:|--------|------|
+| `id` | ✅ | 唯一标识 | 资产 ID |
+| `kind` | ✅ | `artifact` / `guidance` / `enforced` / `knowledge` | 资产种类 |
+| `sync_policy` | ✅ | `engine_only` / `copy_to_project` / `internal` | 同步策略 |
+| `status` | ✅ | `active` / `retired` | 生命周期状态 |
+
+### 1.2 kind 语义
+
+| kind | 含义 | 目录 | 额外字段 |
+|------|------|------|----------|
+| `artifact` | 产出模板（AI 按此格式写产出） | design/build/verify/operate | `title` |
+| `guidance` | 工程经验/审查指导（注入 AI prompt） | 各 stage + shared | `title` + `triggers` |
+| `enforced` | 强制检查清单（gate bridge 聚合执行） | 各 stage（`enforced.md`） | `gate` + `checks` |
+| `knowledge` | 知识条目（决策规则/模式） | 主要 shared | `title` |
+
+### 1.3 各 kind 额外字段
+
+**guidance 必填 `triggers`**（非空数组，否则永不注入=死文件）：
+```yaml
+triggers: [并发, 线程, 锁]
+```
+
+**enforced 必填 `gate` + `checks`**：
+```yaml
+gate: build-gate
+checks:
+  - id: TS-Q01
+    executor: regex_pattern_scan
+    rule: 禁止 as any
+    severity: error
+    check_type: deterministic
+    evidence_required: [...]
+    gate: build-gate
+    target: self
+```
+
+**gate 合法值**：`design-gate` / `build-gate` / `verify-gate` / `operate-gate` / `slice-gate` / `shared-gate`
+
+**check.executor 合法值**（须在 gate_executors 注册）：
+`regex_pattern_scan` / `document_structure` / `file_evidence` / `external_command` / `tsc_compile` / `vitest_run` / `file_scope_check` / `test_count_check` / `lazy_pattern_check` / `cross_validation` / `upstream_gate_check` / `probe` / `semantic`（客户端 AI 评判，引擎不执行）
+
+---
+
+## 二、目录结构（归零重构后按阶段）
+
+```
+templates/
+  design/     需求→架构
+  build/      代码实现
+  verify/     测试审查
+  operate/    部署运维
+  shared/     跨阶段通用（knowledge/guidance + enforced.md + 切片聚合检查）
+  scaffolds/  代码脚手架（.hbs，无 frontmatter）
+  profiles/   产品配置（.yaml，无 frontmatter）
+```
+
+每个 stage 目录（design/build/verify/operate）含三种文件：
+- `<主题>.md`（artifact）— 产出模板
+- `<审查主题>.md`（guidance）— 工程经验（带 triggers）+ 审查 pattern 正文（`## CHECK-ID:` section，regex_pattern_scan 读取）
+- `enforced.md`（enforced）— 该阶段强制检查清单（gate bridge 聚合）
+
+---
+
+## 三、check 聚合机制
+
+gate 不再是独立 YAML 配置文件，而是由 `gate_registry_bridge` 从 enforced 资产的 `checks` 按 `check.gate` 聚合：
+- 每个 check 自带 `gate` 字段声明归属
+- bridge 按 `check.gate` 分组（非按 asset.stage，支持规则跨 stage 引用）
+- regex_pattern_scan 执行器按 check.id 自动定位含 pattern 正文的规则文件（`## CHECK-ID:` section）
+
+---
+
+## 四、旧字段进 extra（不在顶层）
+
+归零重构前的旧字段（type/stage/domain/lifecycle_status/name/scope/authority/priority/owner_mechanism_id 等）保留在 `extra` 子对象，不在顶层：
+
+```yaml
+extra:
+  name: architecture-rules
+  type: constraint
+  scope: ['*']
+  authority: supporting
+  lifecycle_status: active
+  stage: design
+```
+
+**禁止**：`type`/`stage`/`domain`/`lifecycle_status`/`name` 出现在 frontmatter 顶层（护栏强制）。
+
+---
+
+## 五、合规检查（tests/architecture/zero_refactor_guardrails.test.ts）
+
+| # | 规则 | 说明 |
+|---|------|------|
+| 1 | 所有 .md 必须有合法 `kind` | artifact/guidance/enforced/knowledge |
+| 2 | guidance 必须有 `triggers` 或 `owner_mechanism` | 否则死文件（待治理=0） |
+| 3 | enforced 必须有 `gate` + 非空 `checks` | checks>=1 |
+| 4 | 顶层禁止旧字段 | type/stage/domain/lifecycle_status/name 进 extra |
+| 5 | sync_policy 3 合法值 | engine_only/copy_to_project/internal |
+| 6 | status 仅 active/retired | |
+| 7 | gate 合法值 | design/build/verify/operate/slice/shared-gate |
+| 8 | check.id 在 gate 内唯一 | |
+| 9 | 每个 stage 有 enforced.md | design/build/verify/operate/shared |

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

@@ -0,0 +1,283 @@
+---
+id: 模版贡献指南
+kind: guidance
+title: 模版贡献指南
+sync_policy: engine_only
+status: active
+triggers:
+  - 新增模版文件、模版贡献、模版资产维护
+extra:
+  name: template-contribution-guide
+  type: constraint
+  authority: supporting
+  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

@@ -0,0 +1,63 @@
+---
+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
+  authority: canonical
+  priority: P0
+  consumes:
+    - template_asset_contract_registry
+    - template_init_sync
+    - knowledge_index_manager
+  hard_blocks:
+    - internal_asset_leak
+    - cross_stack_injection
+    - unregistered_asset_sync
+  fallback: manual_required
+  required_evidence:
+    - visibility_contract
+    - sync_manifest
+    - runtime_consumption_trace
+  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 等内部术语。