soloforge 1.1.33 → 1.1.34

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

@@ -0,0 +1,147 @@
+---
+name: template-contribution-guide
+type: governance_rule
+asset_kind: governance_rule
+owner_mechanism_id: mc-standard-asset-contract
+authority: supporting
+specificity: 5
+lifecycle_status: active
+routes: ['*']
+scope:
+  - '*'
+when: '新增模版文件、模版贡献、模版资产维护'
+stages: ["*"]
+---
+
+# 新增模版文件检查清单
+
+向 `templates/` 目录新增文件时，必须按以下步骤操作。
+
+> **权威规范**：字段合法值、必填/选填矩阵、命名规则详见 `templates/internal/rules/模版Frontmatter规范.md`。
+
+---
+
+## 一、确定目录
+
+| 目录 | `type` | 职责 |
+|------|--------|------|
+| `patterns/` | `pattern` | 用户编码规范/设计模式 |
+| `procedures/` | `procedure` / `pipeline_procedure` | 开发流程/管线工作流 |
+| `artifacts/` | `artifact_template` / `acceptance_template` | 产出物模版/验收交付模版 |
+| `rules/` | `review_rule` | 审查/校验规则 |
+| `internal/rules/` | `governance_rule` | 引擎治理硬规则 |
+| `internal/patterns/` | `pattern` | 引擎运行时模式 |
+| `domain/` | `domain` | 领域知识 |
+| `checklists/` | `checklist` | 验收清单（打勾式） |
+| `gates/` | YAML 配置 | 阶段门控（独立格式，不纳入 .md 资产体系） |
+| `scaffolds/` | `.hbs` 模版 | 代码脚手架（无 frontmatter，由脚手架引擎直接消费） |
+| `profiles/` | `.yaml` 配置 | 产品配置（无 frontmatter，由配置加载器直接消费） |
+
+**验收文件归属**：
+- 打勾式清单（消费者是 AI 校验）→ `checklists/`（type: `checklist`）
+- 产出物格式模版（消费者是 AI 按模版输出制品）→ `artifacts/`（type: `artifact_template`）
+
+**系统类型分区**：`artifacts/`、`rules/`、`gates/` 内部按 `shared/` + `existing-system/` + `new-system/` 二级分区。其余目录无系统类型差异。
+
+---
+
+## 二、填写 Frontmatter
+
+### 必填字段
+
+```yaml
+---
+name: "文件中文名（kebab-case 或中文）"
+type: "见上表 9 种合法值"
+asset_kind: "与 type 兼容的注册侧分类"
+routes:
+  - "IntentRoute 值或 *"
+scope:
+  - "backend / frontend / infrastructure / *"
+stages:
+  - "需求分析 / 现有系统分析 / 架构设计 / 详细设计 / 任务规划 / 编码与单元测试 / 代码审查 / 联调验证"
+  - "*"
+lifecycle_status: "active / deprecated / draft"
+owner_mechanism_id: "mc-xxx-yyy"
+---
+```
+
+### 选填字段
+
+| 字段 | 合法值 | 说明 |
+|------|--------|------|
+| `system_scope` | `shared` / `existing-system` / `new-system` | 默认 `shared` |
+| `specificity` | 2-5 整数 | 优先级权重，默认 3 |
+| `authority` | `canonical` / `supporting` | 仅 `internal/rules/` 和 `rules/shared/` 允许 `canonical` |
+| `when` | 自然语言触发描述 | 描述什么场景下注入 |
+| `primary_triggers` | 关键词列表 | 用于关键词匹配 |
+| `consumes` | mechanism_id 列表 | 此资产依赖哪些机制产出 |
+| `consumed_by` | mechanism_id 列表 | 此资产被哪些机制消费 |
+| `emits` | 产物标识列表 | 此资产产出什么 |
+| `required_evidence` | 证据标识列表 | 执行此资产需要什么证据 |
+| `products` | `*` 或产品类型 | 当前全部 `*` |
+
+### 禁止字段
+
+| 字段 | 处理 |
+|------|------|
+| `status` | 已废弃，统一用 `lifecycle_status` |
+| `migration_note` | 已废弃，运行时无意义 |
+
+---
+
+## 三、注册到代码
+
+1. **ASSET_MANIFEST** — `src/engine/templates/asset_manifest.ts`
+2. **ExplicitAssetRegistry** — `src/engine/templates/explicit_asset_registry/`
+3. **type 配置** — 确认 type 在 `STAGE_TYPE_MAP`（`src/engine/pipeline/intent_expander/knowledge.ts`）和 `EXECUTION_SHAPE_ALLOWED_TYPES`（`src/engine/knowledge/knowledge_injection_boundary.ts`）中至少出现一次
+
+---
+
+## 四、命名规范
+
+1. **用字统一**：文件名和内容中使用 `模版`，不使用 `模板`
+2. **procedures/ 后缀**：
+   - `流程` — 标准执行流程
+   - `工作流` — 管线直接调度的工作流
+   - `流水线` — 自动化多步骤流水线
+3. **机制 ID**：`mc-` 前缀 + kebab-case。新建机制 ID 需在 `docs/SoloForge-工作流管线设计方案.md` 4.4 节登记
+
+---
+
+## 五、机制簇规则
+
+同主题文件遵循五层纵深模型：
+
+```
+规则(governance_rule) → 流程(procedure) → 产出(artifact_template)
+规范(pattern) → 审查(review_rule)
+```
+
+同 `owner_mechanism_id` 簇内的文件应覆盖不同层次。`consumes`/`consumed_by` 通过 `emits`/`required_evidence` 值匹配自动推断。
+
+---
+
+## 六、运行验证
+
+```bash
+# 合规测试（12 条规则，全部通过）
+npx vitest run tests/architecture/template_frontmatter_compliance.test.ts
+
+# 完整架构测试
+npx vitest run tests/architecture/
+
+# 全量测试
+npm test -- --run
+```
+
+---
+
+## 跳过任何步骤的后果
+
+| 跳过步骤 | 失败测试 |
+|---------|---------|
+| frontmatter 字段缺失 | `template_frontmatter_compliance.test.ts` |
+| 代码注册缺失 | `template_integrity.test.ts` |
+| type 未配置 | `template_consumption_coverage.test.ts` |
+| 新文件无法被消费 | `template_consumption_coverage.test.ts` |