---
name: template-frontmatter-spec
type: governance_rule
asset_kind: governance_rule
owner_mechanism_id: mc-standard-asset-contract
authority: canonical
specificity: 5
lifecycle_status: active
routes: ['*']
when: 模版文件写入、模版 frontmatter 校验、模版资产注册
stages: ["*"]
---

# 模版 Frontmatter 规范

> 权威来源：本文档定义 `templates/` 下所有 .md 文件的 frontmatter 字段合法值、必填/选填、语义。
> 引用标准：`docs/SoloForge-工作流管线设计方案.md` 第四章（8 TaskStage）、`src/types/pipeline.ts`（IntentRoute）。

---

## 一、字段体系概览

### 1.1 `type` — 消费侧分类（知识注入管线使用）

**必填**。每个 .md 文件必须声明 `type`。

**合法值（9 种）**：

| type | 含义 | 对应目录 | asset_kind 兼容映射 |
|------|------|----------|-------------------|
| `pattern` | 编码规范/设计模式 | patterns/, internal/patterns/ | pattern |
| `procedure` | 开发流程/工作流 | procedures/ | procedure |
| `pipeline_procedure` | 管线级流程 | procedures/ | procedure |
| `domain` | 领域知识 | domain/ | domain_knowledge |
| `artifact_template` | 产出物模版 | artifacts/ | artifact_template |
| `acceptance_template` | 验收交付模版 | artifacts/ | acceptance_template |
| `review_rule` | 审查/校验规则 | rules/ | review_rule |
| `governance_rule` | 引擎治理硬规则 | internal/rules/, gates/ | hard_rule |
| `checklist` | 验收清单（打勾式） | checklists/ | checklist |

**规则**：
- `type` 决定文件在知识注入管线中的路由和过滤方式
- `asset_kind` 为注册侧分类，由 `template_asset_contract_registry` 使用，保持向后兼容但不再作为消费依据
- **废弃的 type 值**：`hard_rule` → 使用 `governance_rule`；`rule` → 使用 `governance_rule`；`domain_knowledge` → 使用 `domain`；`knowledge_pattern` → 使用 `pattern`；`capability_knowledge_doc` → 使用 `pattern`；`pipeline_rule` → 使用 `review_rule`；`pipeline_artifact` → 使用 `artifact_template`

### 1.2 `routes` — 路由白名单

**必填**。声明此资产在哪些 IntentRoute 下生效。

**合法值**：
- IntentRoute 10 个值：`skip_chat`, `direct_answer`, `artifact_generation`, `source_extraction`, `code_change`, `analysis`, `review`, `acceptance`, `planning`, `operation`
- 通配符 `*`：表示对所有路由生效

**禁止值**：中文描述、文件名自引用、内部工具名、`all`

### 1.3 `scope` — 技术栈适用范围

**必填**。声明此资产适用的技术栈。

**合法值**：
- `backend` — 后端技术栈
- `frontend` — 前端技术栈
- `infrastructure` — 基础设施
- `*` — 所有技术栈（通用）

**注意**：`scope` 仅表达技术栈语义。系统类型（新系统/老系统/共用）由 `system_scope` 字段表达。

### 1.4 `system_scope` — 系统类型适用范围

**选填**。声明此资产适用的系统类型（新系统/老系统）。

**合法值**：
- `shared` — 两类系统共用（默认）
- `existing-system` — 仅老系统改造
- `new-system` — 仅新系统

**默认值**：如果不声明，视为 `shared`。

### 1.5 `stages` — 任务阶段

**必填**。声明此资产在哪些任务阶段生效。

**合法值**（以 `docs/SoloForge-工作流管线设计方案.md` 第四章 8 个 TaskStage 为权威来源）：

| 阶段名 | 英文标识 | 适用系统 |
|--------|---------|---------|
| `需求分析` | requirement_analysis | 共用 |
| `现有系统分析` | existing_system_analysis | 仅老系统 |
| `架构设计` | architecture_design | 共用 |
| `详细设计` | detailed_design | 共用 |
| `任务规划` | slice_planning | 共用 |
| `编码与单元测试` | coding | 共用 |
| `代码审查` | code_review | 共用 |
| `联调验证` | integration_verification | 共用 |

**通配符 `*`**：表示所有阶段均生效。

**gates/ YAML 使用的扩展阶段**（仅限 gates/ 目录内的 YAML 文件使用）：

gates/ 可使用上述 8 个阶段，以及以下细粒度阶段：`交付`、`会话启动`、`决策研讨`、`编码就绪`、`验证验收`、`发布后审查`、`验收测试规划`、`试运行`、`联调缺陷`。.md 文件不允许使用这些扩展阶段。

### 1.6 `specificity` — 优先级权重

**选填**。当多个资产同时匹配时，specificity 值高的优先注入。

**取值范围**：2-5（整数）
- 2 = 通用参考
- 3 = 默认权重
- 4 = 高优先级
- 5 = 核心规则

**禁止值**：0、1、6+（超出范围）

### 1.7 `authority` — 权威性声明

**选填**。默认 `supporting`。

**合法值**：
- `canonical` — 权威规则，仅在以下目录允许：
  - `internal/rules/`（引擎硬规则）
  - `rules/shared/`（核心审查规则，如 SOLID 代码审查规则）
- `supporting` — 辅助参考，其他所有目录的默认值

### 1.8 `products` — 产品类型适用范围

**选填**。当前全部为 `['*']`（通配），产品差异化能力待后续版本启用。

**合法值**：`*` | 产品类型标识（未来定义，与 `profiles/` 下的配置对齐）

### 1.9 `owner_mechanism_id` — 机制归属

**必填**（scaffolds/ 和 profiles/ 除外）。声明此资产属于哪个机制。

**命名规范**：`mc-` 前缀 + kebab-case。示例：`mc-ood-solid-contract`。

**注册要求**：新建机制 ID 需在 `docs/SoloForge-工作流管线设计方案.md` 4.4 节中登记。

### 1.10 `consumes` / `emits` / `consumed_by` — 依赖链

**选填**。用于追溯机制间的依赖关系。

- `emits`：此资产产出什么（产物标识）
- `consumes`：此资产依赖哪个机制产出（mechanism_id 列表）
- `consumed_by`：此资产被哪个机制消费（mechanism_id 列表）
- `required_evidence`：此资产需要什么证据才能执行

**推断算法**：同 `owner_mechanism_id` 簇内，如果文件 A 的 `emits` 值 X 与文件 B 的 `required_evidence` 值 X 匹配，则 B 的 `consumes` 应包含 A 的 `owner_mechanism_id`，A 的 `consumed_by` 应包含 B 的 `owner_mechanism_id`。跨簇无 `required_evidence` 匹配时不填。

### 1.11 `when` / `primary_triggers` — 触发条件

**选填**。声明此资产在什么用户意图下被注入。

- `when`：自然语言描述触发条件
- `primary_triggers`：关键词列表，用于关键词匹配

**注意**：同簇文件共享触发词是正常的。跨簇文件应避免使用完全相同的触发词，防止路由竞争。

### 1.12 `lifecycle_status` — 生命周期状态

**必填**。唯一的状态字段。

**合法值**：`active` | `deprecated` | `draft`

**禁止**：不允许同时存在 `status` 和 `lifecycle_status`。统一使用 `lifecycle_status`。

---

## 二、禁止和清理字段

以下字段已废弃，不得出现在新文件中，存量文件应逐步清理：

| 字段 | 原用途 | 处理方式 |
|------|--------|---------|
| `status` | 与 `lifecycle_status` 语义完全重复 | 移除，保留 `lifecycle_status` |
| `migration_note` | 迁移标记，运行时无意义 | 全部移除 |

---

## 三、命名规范

### 3.1 文件名用字

- 统一使用 `模版`（不使用 `模版`）
- 已有文件中 `模版` 应逐步替换为 `模版`

### 3.2 procedures/ 文件后缀

procedures/ 目录下文件后缀按语义区分：

| 后缀 | 含义 | 使用场景 |
|------|------|---------|
| `流程` | 标准执行流程 | 功能开发流程、调试排查流程等 |
| `工作流` | 管线工作流 | 架构设计工作流、OOD设计工作流等由管线直接调度 |
| `流水线` | 自动化流水线 | 安全加固流水线、迁移流水线等自动化多步骤 |

---

## 四、目录归属规则

### 4.1 每目录对应的 type 和职责

| 目录 | type 主体 | 职责 | 系统类型分区 |
|------|----------|------|------------|
| `patterns/` | `pattern` | 用户编码规范 | 无（通用） |
| `procedures/` | `procedure` / `pipeline_procedure` | 开发流程 | 无（通用） |
| `artifacts/` | `artifact_template` | 产出物模版 | shared/ + existing-system/ + new-system/ |
| `internal/rules/` | `governance_rule` | 引擎硬规则 | 无（通用） |
| `internal/patterns/` | `pattern` | 引擎运行时模式 | 无（通用） |
| `rules/` | `review_rule` | 审查规则 | shared/ + existing-system/ + new-system/ |
| `gates/` | `governance_rule`（如纳入） | 阶段门控配置 | shared/ + existing-system/ + new-system/ |
| `domain/` | `domain` | 领域知识 | 无（通用） |
| `checklists/` | `checklist` | 验收清单 | 无（通用） |
| `scaffolds/` | 不适用（.hbs） | 代码脚手架 | 无 |
| `profiles/` | 不适用（.yaml） | 产品配置 | 无 |

### 4.2 验收文件归属

- **打勾式验收清单**（消费者是 AI 做校验） → `checklists/`（type: `checklist`）
- **产出物格式模版**（消费者是 AI 按模版输出制品） → `artifacts/`（type: `artifact_template`）
- 同名主题只能二选一：如果内容是清单则放 `checklists/`，如果内容是格式模版则放 `artifacts/`

### 4.3 排除范围

以下目录不纳入模版资产体系（无 frontmatter、无机制注册）：
- `scaffolds/`（22 个 .hbs 文件）— 由脚手架引擎直接消费
- `profiles/`（3 个 .yaml 文件）— 由产品配置加载器直接消费

---

## 五、字段必填矩阵

| 字段 | pattern | procedure | pipeline_procedure | domain | artifact_template | acceptance_template | review_rule | governance_rule | checklist |
|------|:-------:|:---------:|:------------------:|:------:|:-----------------:|:-------------------:|:-----------:|:---------------:|:---------:|
| `type` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `asset_kind` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `routes` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `scope` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `stages` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `lifecycle_status` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `owner_mechanism_id` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `when` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `system_scope` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `specificity` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `authority` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `products` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `consumes` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `emits` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `consumed_by` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `primary_triggers` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| `required_evidence` | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ | ○ |

✅ = 必填　○ = 选填

---

## 六、合规检查规则

以下规则在 `tests/architecture/template_frontmatter_compliance.test.ts` 中强制执行：

| # | 规则 | 级别 | 说明 |
|---|------|------|------|
| 1 | `type` 必填且在 9 种合法值内 | 硬规则 | 所有 .md 文件 |
| 2 | `asset_kind` 必填 | 硬规则 | 所有 .md 文件 |
| 3 | `routes` 值在 IntentRoute 10 个值或 `*` 内 | 硬规则 | |
| 4 | `scope` 值在 `backend`/`frontend`/`infrastructure`/`*` 内 | 硬规则 | |
| 5 | `system_scope`（如有）在合法系统类型内 | 硬规则 | |
| 6 | `stages` 是 8 个 TaskStage 之一或 `*` | 硬规则 | |
| 7 | `specificity`（如有）在 2-5 范围内 | 硬规则 | |
| 8 | `authority`（如有）在 `canonical`/`supporting` 内 | 硬规则 | |
| 9 | `lifecycle_status` 必填 | 硬规则 | 唯一状态字段，禁止与 `status` 并存 |
| 10 | `canonical` authority 仅允许出现在 `internal/rules/` 和 `rules/shared/` | 硬规则 | |
| 11 | `owner_mechanism_id` 必填 | 硬规则 | scaffolds/profiles 除外 |
| 12 | frontmatter YAML 格式合规 | 硬规则 | 禁止 `]` 后直接跟字段名（如同行 `routes: ['*']products:`） |

新增机制 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/）
