@wneng/create-keel 0.1.0

package/src/templates/ci-gitee/files/pipeline.yml

@@ -0,0 +1,18 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        run: echo "checkout <%= it.options.projectName %>"
+      - name: contract lint
+        run: echo "spectral lint contracts/openapi/api.yaml"
+      - name: json schema validate
+        run: echo "ajv-cli validate -s contracts/**/*.schema.json"
+      - name: dependency scan
+        run: echo "npm audit / pip-audit / trivy"

package/src/templates/ci-gitee/fragment.yaml

@@ -0,0 +1,9 @@
+name: ci-gitee
+version: 1.0.0
+appliesWhen:
+  ci: gitee
+priority: 20
+files:
+  - from: files/pipeline.yml
+    to: .gitee/pipelines/ci.yml
+    render: true

package/src/templates/ci-github/files/ci.yml

@@ -0,0 +1,17 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: contract lint
+        run: echo "spectral lint for <%= it.options.projectName %>"
+      - name: json schema validate
+        run: echo "ajv-cli validate"
+      - name: dependency scan
+        run: echo "npm audit / pip-audit / trivy"

package/src/templates/ci-github/fragment.yaml

@@ -0,0 +1,9 @@
+name: ci-github
+version: 1.0.0
+appliesWhen:
+  ci: github
+priority: 20
+files:
+  - from: files/ci.yml
+    to: .github/workflows/ci.yml
+    render: true

package/src/templates/contracts-base/files/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Contracts Changelog
+
+All notable changes to the contracts in this repository will be documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/) and versions follow SemVer.
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffold.

package/src/templates/contracts-base/files/README.md

@@ -0,0 +1,75 @@
+# contracts/ — 契约权威
+
+本目录承载 **<%= it.options.projectName %>** 的机器可消费契约：所有 API、事件、错误码、领域模型、状态机、环境变量。
+
+任何与契约冲突的实现都视为 bug；任何修改契约的 PR 都必须在同一 PR 内更新 `CHANGELOG.md`。
+
+## 1. 目录结构
+
+```
+contracts/
+├── README.md                       # 本文件
+├── CHANGELOG.md                    # 契约变更日志（CI 强制同 PR 更新）
+├── openapi/
+<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>│   ├── api.yaml                    # OpenAPI 3.x 主文件
+<% } %><% if (it.options.contract === 'events-only' || it.options.contract === 'rest+events') { %>│   └── asyncapi.yaml               # 消息 / 事件驱动接口
+<% } %>├── dictionaries/                   # 数据字典与领域模型
+├── states/                         # 业务状态机（按需）
+├── errors/                         # 错误规范
+├── events/                         # 事件契约
+├── resources/                      # 示例与 Mock
+├── environment/                    # 环境契约
+└── tests/                          # 可执行测试契约
+```
+
+## 2. 进入 contracts/ 的文件要求
+
+- **格式必须结构化、版本可控、工具或 AI 可直接消费**：YAML / JSON / Gherkin / OpenAPI / AsyncAPI / JSON Schema
+- 不允许放入非结构化自由文本；唯一例外：`README.md`、`CHANGELOG.md`
+- 任何变更都可能触发下游代码重新生成；PR 描述必须说明影响范围
+- 示例中不得包含真实 PII；占位符规则与完整 PII 政策见 [`docs/governance/security.md`](../docs/governance/security.md)
+
+## 3. 命名与格式
+
+- 文件名：`kebab-case`，例 `user-registration.yaml`
+- Schema 字段名：`camelCase`
+- 错误码：`DOMAIN.SUBDOMAIN.REASON` 全大写，例 `USER.AUTH.TOKEN_EXPIRED`
+- 枚举值：`UPPER_SNAKE_CASE`
+
+## 4. 版本策略（SemVer）
+
+- **MAJOR**：破坏性变更（删除字段、改变语义、不兼容的路径变更）
+- **MINOR**：向后兼容的新增（新端点、新可选字段）
+- **PATCH**：修订描述、修正示例、补充文档
+
+版本号位置：
+
+- `contracts/openapi/api.yaml` 的 `info.version`
+- `contracts/CHANGELOG.md` 顶部
+- 独立发布时使用 Git Tag `contracts-vX.Y.Z`
+
+## 5. 变更日志
+
+`contracts/CHANGELOG.md` 必须与契约变更在**同一 PR** 内更新。CI 强制校验。格式遵循 [Keep a Changelog](https://keepachangelog.com/)。
+
+## 6. 废弃流程
+
+1. schema 标注 `deprecated: true` 与 `x-sunset: YYYY-MM-DD`
+2. CHANGELOG 记录废弃原因与替代方案
+3. 至少保留一个 MINOR 版本周期（或 30 天，取较长者）后才能移除
+4. 移除时 MAJOR+1
+
+## 7. 契约 → 代码一致性
+
+- 代码生成器、mock、Pact 验证脚本统一在 `tools/contract/`
+- 由契约生成的代码放各模块的 `generated/` 子目录，**禁止手改**
+- CI 校验"重新生成 → `git diff --exit-code generated/`"，未对齐即阻断
+
+<% if (it.options.integrations) { %>## 8. 集成对接联动
+
+本仓库已启用 `integrations`。契约的任何变更影响某 pair 时，**必须**在同一 PR 同步更新 `docs/06-集成对接/<pair>/`。完整规则见 `docs/governance/integrations.md`。
+<% } %>
+
+## 9. 守门
+
+`contracts/` 在 `CODEOWNERS` 中归 `@arch-team` 守门。任何契约变更需要架构组 review。

package/src/templates/contracts-base/files/_ai-policy.yaml

@@ -0,0 +1,20 @@
+# AI 访问策略：contracts/
+# 依据 ADR-0003 §4.1
+mode: generated
+source-of-truth:
+  - "docs/01-背景与需求/**"
+  - "docs/02-系统方案与架构/**"
+last-aligned-with:
+  source-commit: null
+  aligned-at: null
+human-review-required: true
+notes: |
+  contracts/ 是 AI 派生区。
+  AI 根据 docs/01-需求 与 docs/02-架构 主动维护 OpenAPI / Schema / 错误码 / 字典 / 状态机。
+  人可以编辑契约（作为下次 AI 生成的输入语境），但应当走 PR 让架构组评审契约的合理性。
+
+  下列子目录在各自 _ai-policy.yaml 中有局部覆盖：
+  - tests/acceptance/   suggest（Gherkin 是人表达业务）
+  - tests/contracts/    suggest（消费端驱动，本仓库不主动）
+
+  README.md 与 CHANGELOG.md 沿用父策略 generated（README 视项目情况可改 suggest）。

package/src/templates/contracts-base/files/dictionaries/domain-models.yaml

@@ -0,0 +1,3 @@
+# Domain models
+# Add entities, fields, and constraints here. Field names in camelCase.
+models: {}

package/src/templates/contracts-base/files/dictionaries/enums.yaml

@@ -0,0 +1,3 @@
+# Global enumeration values.
+# Enum values are UPPER_SNAKE_CASE.
+enums: {}

package/src/templates/contracts-base/files/environment/.env.example

@@ -0,0 +1,3 @@
+# Copy this file to `.env` and fill real values.
+# Keep secrets OUT of version control.
+NODE_ENV=development

package/src/templates/contracts-base/files/environment/env.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/env.json",
+  "title": "EnvironmentVariables",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "NODE_ENV": { "type": "string", "enum": ["development", "test", "production"] }
+  }
+}

package/src/templates/contracts-base/files/errors/error-codes.yaml

@@ -0,0 +1,6 @@
+# Error codes
+# Format: DOMAIN.SUBDOMAIN.REASON (all uppercase).
+codes:
+  SYSTEM.INTERNAL.UNEXPECTED:
+    httpStatus: 500
+    message: "An unexpected error occurred."

package/src/templates/contracts-base/files/errors/error-response.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://example.com/schemas/error-response.json",
+  "title": "ErrorResponse",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["code", "message"],
+  "properties": {
+    "code": { "type": "string" },
+    "message": { "type": "string" },
+    "details": { "type": "object" }
+  }
+}

package/src/templates/contracts-base/fragment.yaml

@@ -0,0 +1,53 @@
+name: contracts-base
+version: 1.0.0
+appliesWhen: {}
+priority: 10
+files:
+  - from: files/_ai-policy.yaml
+    to: contracts/_ai-policy.yaml
+    render: false
+  - from: files/README.md
+    to: contracts/README.md
+    render: true
+  - from: files/CHANGELOG.md
+    to: contracts/CHANGELOG.md
+    render: false
+  - from: files/dictionaries/domain-models.yaml
+    to: contracts/dictionaries/domain-models.yaml
+    render: false
+  - from: files/dictionaries/enums.yaml
+    to: contracts/dictionaries/enums.yaml
+    render: false
+  - from: files/errors/error-codes.yaml
+    to: contracts/errors/error-codes.yaml
+    render: false
+  - from: files/errors/error-response.schema.json
+    to: contracts/errors/error-response.schema.json
+    render: false
+  - from: files/environment/.env.example
+    to: contracts/environment/.env.example
+    render: false
+  - from: files/environment/env.schema.json
+    to: contracts/environment/env.schema.json
+    render: false
+  - from: files/states-gitkeep
+    to: contracts/states/.gitkeep
+    render: false
+  - from: files/events-gitkeep
+    to: contracts/events/.gitkeep
+    render: false
+  - from: files/resources-examples-gitkeep
+    to: contracts/resources/examples/.gitkeep
+    render: false
+  - from: files/resources-mocks-gitkeep
+    to: contracts/resources/mocks/.gitkeep
+    render: false
+  - from: files/tests-acceptance-gitkeep
+    to: contracts/tests/acceptance/.gitkeep
+    render: false
+  - from: files/tests-contracts-gitkeep
+    to: contracts/tests/contracts/.gitkeep
+    render: false
+  - from: files/tests-postman-gitkeep
+    to: contracts/tests/postman-collections/.gitkeep
+    render: false

package/src/templates/contracts-events/files/asyncapi.yaml

@@ -0,0 +1,8 @@
+asyncapi: 3.0.0
+info:
+  title: <%= it.options.projectName %>
+  version: 0.1.0
+  description: Event-driven contract. Document publish/subscribe channels here.
+channels: {}
+operations: {}
+components: {}

package/src/templates/contracts-events/fragment.yaml

@@ -0,0 +1,9 @@
+name: contracts-events
+version: 1.0.0
+appliesWhen:
+  contract: events-only
+priority: 20
+files:
+  - from: files/asyncapi.yaml
+    to: contracts/openapi/asyncapi.yaml
+    render: true

package/src/templates/contracts-rest/files/api.yaml

@@ -0,0 +1,7 @@
+openapi: 3.1.0
+info:
+  title: <%= it.options.projectName %>
+  version: 0.1.0
+  description: REST API contract. Edit freely; keep examples free of PII.
+paths: {}
+components: {}

package/src/templates/contracts-rest/fragment.yaml

@@ -0,0 +1,9 @@
+name: contracts-rest
+version: 1.0.0
+appliesWhen:
+  contract: rest
+priority: 20
+files:
+  - from: files/api.yaml
+    to: contracts/openapi/api.yaml
+    render: true

package/src/templates/contracts-rest-events/files/api.yaml

@@ -0,0 +1,7 @@
+openapi: 3.1.0
+info:
+  title: <%= it.options.projectName %>
+  version: 0.1.0
+  description: REST API contract. Edit freely; keep examples free of PII.
+paths: {}
+components: {}

package/src/templates/contracts-rest-events/files/asyncapi.yaml

@@ -0,0 +1,8 @@
+asyncapi: 3.0.0
+info:
+  title: <%= it.options.projectName %>
+  version: 0.1.0
+  description: Event-driven contract. Document publish/subscribe channels here.
+channels: {}
+operations: {}
+components: {}

package/src/templates/contracts-rest-events/fragment.yaml

@@ -0,0 +1,12 @@
+name: contracts-rest-events
+version: 1.0.0
+appliesWhen:
+  contract: rest+events
+priority: 20
+files:
+  - from: files/api.yaml
+    to: contracts/openapi/api.yaml
+    render: true
+  - from: files/asyncapi.yaml
+    to: contracts/openapi/asyncapi.yaml
+    render: true

package/src/templates/deploy-bare-metal/files/release-checklist.md

@@ -0,0 +1,8 @@
+# Release Checklist — <%= it.options.projectName %>
+
+- [ ] All tests pass on the target branch
+- [ ] `contracts/CHANGELOG.md` entry covers this release
+- [ ] Artifact built and signed
+- [ ] Target host reachable and in maintenance window
+- [ ] Rollback script rehearsed
+- [ ] Monitoring dashboards open

package/src/templates/deploy-bare-metal/fragment.yaml

@@ -0,0 +1,9 @@
+name: deploy-bare-metal
+version: 1.0.0
+appliesWhen:
+  deploy: bare-metal
+priority: 20
+files:
+  - from: files/release-checklist.md
+    to: deploy/checklists/release-checklist.md
+    render: true

package/src/templates/deploy-common/files/README.md

@@ -0,0 +1,5 @@
+# deploy/
+
+Release artifacts and per-environment configuration for
+**<%= it.options.projectName %>**. The application-vs-infrastructure split
+follows `AGENTS.md` §11: infrastructure lives in `ops/`.

package/src/templates/deploy-common/fragment.yaml

@@ -0,0 +1,8 @@
+name: deploy-common
+version: 1.0.0
+appliesWhen: {}
+priority: 10
+files:
+  - from: files/README.md
+    to: deploy/README.md
+    render: true

package/src/templates/deploy-docker-compose/files/compose.override.example.yaml

@@ -0,0 +1,4 @@
+services:
+  app:
+    ports:
+      - "8080:8080"

package/src/templates/deploy-docker-compose/files/docker-compose.yaml

@@ -0,0 +1,4 @@
+services:
+  app:
+    image: <%= it.options.projectName %>:local
+    restart: unless-stopped

package/src/templates/deploy-docker-compose/fragment.yaml

@@ -0,0 +1,12 @@
+name: deploy-docker-compose
+version: 1.0.0
+appliesWhen:
+  deploy: docker-compose
+priority: 20
+files:
+  - from: files/docker-compose.yaml
+    to: deploy/compose/docker-compose.yaml
+    render: true
+  - from: files/compose.override.example.yaml
+    to: deploy/compose/compose.override.example.yaml
+    render: false

package/src/templates/deploy-kubernetes/files/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: <%= it.options.projectName %>
+description: Helm chart for <%= it.options.projectName %>
+type: application
+version: 0.1.0
+appVersion: "0.1.0"

package/src/templates/deploy-kubernetes/files/deployment.yaml

@@ -0,0 +1,18 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: <%= it.options.projectName %>
+  namespace: <%= it.options.projectName %>
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: <%= it.options.projectName %>
+  template:
+    metadata:
+      labels:
+        app: <%= it.options.projectName %>
+    spec:
+      containers:
+        - name: app
+          image: <%= it.options.projectName %>:local

package/src/templates/deploy-kubernetes/files/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: <%= it.options.projectName %>

package/src/templates/deploy-kubernetes/files/values.yaml

@@ -0,0 +1,4 @@
+image:
+  repository: <%= it.options.projectName %>
+  tag: local
+replicaCount: 1

package/src/templates/deploy-kubernetes/fragment.yaml

@@ -0,0 +1,18 @@
+name: deploy-kubernetes
+version: 1.0.0
+appliesWhen:
+  deploy: kubernetes
+priority: 20
+files:
+  - from: files/namespace.yaml
+    to: deploy/k8s/namespace.yaml
+    render: true
+  - from: files/deployment.yaml
+    to: deploy/k8s/deployment.yaml
+    render: true
+  - from: files/Chart.yaml
+    to: deploy/helm/Chart.yaml
+    render: true
+  - from: files/values.yaml
+    to: deploy/helm/values.yaml
+    render: true

package/src/templates/docs-skeleton/files/README.md

@@ -0,0 +1,134 @@
+# docs/ — 文档门户
+
+本目录承载所有**面向人类**的文档。机器可消费的契约见 `contracts/`，协作总纲见仓库根 `AGENTS.md`。
+
+## 1. 目录地图
+
+```
+docs/
+├── README.md                       # 本文件，文档入口
+├── 01-背景与需求/                  # PRD、需求调研、竞品分析
+├── 02-系统方案与架构/              # ADR、架构提案、方案对比
+├── 03-工程规范与研发基础设施/      # 编码规范、CI/CD、环境管理
+├── 04-后端详细设计/                # 后端模块设计
+├── 05-前端客户端详细设计/          # 前端 / 客户端模块设计
+<% if (it.options.integrations) { %>├── 06-集成对接/                    # 跨执行环境对接（已启用）
+<% } %>├── assets/                         # 图片、图表源、设计稿
+├── references/                     # 第三方资料（标准、厂商、合规）
+├── governance/                     # 从 AGENTS.md 拆出的细化政策
+├── archive/                        # 退役文档归档
+└── 过程文档/                       # 草稿、会议记录、调研、未定稿
+```
+
+## 2. 正式文档 vs 过程文档
+
+**正式文档**：经过评审、有结论、可作为决策依据的文档。归入编号目录（`01-` 至 `06-`）。
+
+**过程文档**：草稿、讨论、临时调研、未定稿。**只能**进 `过程文档/`。
+
+| 阶段 | 位置 |
+| --- | --- |
+| 正在讨论 | `docs/过程文档/drafts/` |
+| 已开会 | `docs/过程文档/meeting-notes/` |
+| 技术调研 | `docs/过程文档/spike-investigations/` |
+| 结论已采纳 | 提炼到对应编号目录；原文档头部加"已采纳 → 见 …" |
+| 被否决 / 过期 90 天 | 移入 `docs/archive/` |
+
+## 3. 索引同步规则
+
+新增 / 修改可能影响 **启动 / 实现 / 管理** 视角的文档时，**必须同步**：
+
+- 本文件 `docs/README.md`（更新目录地图、新增分类入口、调整子目录约定）
+
+> 历史上 `docs/过程文档/` 曾维护三份手写索引文件（阅读顺序 / 必读清单 / 详细设计导航）。这些被 `AGENTS.md` §0 与本文件 §1、§9 完整覆盖，且无法被 lint 验证一致性，已废弃。AI 与人都用 `grep` / `fileSearch` 检索，不再依赖手维护索引。
+
+## 4. 文档命名规则
+
+- 正式文档：`<编号>-<主题>.md`，例 `02-认证流程方案.md`
+- ADR：`docs/02-系统方案与架构/adr-<NNNN>-<slug>.md`
+- 过程文档：自由命名，但应包含日期或主题以利索引
+
+## 5. 子目录约定的强弱分级
+
+并非所有 docs/ 一级子目录的内部结构都"必守"。按强度分两类。
+
+### 5.1 硬约定（结构与 AI 触达模式绑定，不可调整）
+
+下列目录的子目录划分是**结构性必守**——它们与 ADR-0003 的 access mode 或 governance-lint 检查直接耦合，调整会触发 lint 失败或破坏双闸门：
+
+| 目录 | 必守子目录 | 强制来源 |
+|------|----------|---------|
+| `06-集成对接/` | `<consumer>-to-<producer>/` 命名模式 | [`governance/integrations.md`](governance/integrations.md) |
+| `07-质量与测试/` | `test-plans/` `test-cases/` `defects/` | ADR-0002 + scaffolder |
+| `08-部署与现场实施/` | `templates/`(read-only) + `runbooks/` + `customer-<id>/`(read-only) + `customer-<id>/.pending/`(generated) | ADR-0002 + governance-lint |
+| `10-合规与安全/` | `assessments/`(suggest) + `evidence/`(read-only) | ADR-0002 + governance-lint |
+| `11-市场与对外材料/` | `templates/`(read-only) + `drafts/`(generated) + `published/`(read-only) | ADR-0002 + 双闸门 + governance-lint |
+| `governance/` | 11 个固定文件名 | ADR-0001 + governance-lint |
+| `assets/` | `diagrams/` + `images/` + `design/` | [`governance/assets.md`](governance/assets.md) 引用约定 |
+| `references/` | `standards/` + `vendors/` + `legal/` | [`governance/docs-references.md`](governance/docs-references.md) 元数据规则 |
+| `过程文档/` | `drafts/` + `meeting-notes/` + `spike-investigations/` + 三份索引 | AGENTS.md §5 |
+
+### 5.2 软建议（按项目实际调整）
+
+下列目录的内部结构在各 README 里**仅作建议**，没有 lint 检查；项目可按业务线、团队规模、写作风格自行调整：
+
+| 目录 | 建议（非强制） |
+|------|--------------|
+| `01-背景与需求/` | 可分 `prd/` `research/` `competitive/`，也可扁平 |
+| `02-系统方案与架构/` | 扁平，ADR 按 `adr-<NNNN>-<slug>.md` 命名 |
+| `03-工程规范与研发基础设施/` | 按主题（编码规范 / CI / 环境）扁平组织 |
+| `04-后端详细设计/` | 一模块一文件 `<模块>.md`，或多文件用 `<模块>/` 子目录 |
+| `05-前端客户端详细设计/` | 按"功能 + 平台"或"平台 + 功能"分层，二选一 |
+| `archive/` | 扁平，文件名加 `YYYY-MM-` 日期前缀 |
+| `design/` | `figma-exports/` + `ui-spec/`（scaffolder 默认；可调整） |
+
+调整软建议目录的内部结构**不需要新 ADR**；调整硬约定目录的结构**必须**经过 ADR 修订。
+
+## 6. 特性关联约定
+
+同一特性（feature）通常会跨多个目录产出文档：PRD（01）、架构（02）、后端 / 前端设计（04 / 05）、集成（06）、测试（07）、契约（contracts/）。为了让 `grep` 一秒找全、PR review 能确认齐全：
+
+### 6.1 命名规则
+
+每个特性使用一个稳定的 **kebab-case slug**，匹配 `^[a-z0-9][a-z0-9-]{0,62}$`。slug 一旦确立**不改名**；改名等价于建新特性。
+
+slug 出现在文件名中：
+
+| 层级 | 文件名模式 | 示例（slug = `user-signup`）|
+|------|----------|---------------------------|
+| PRD（01）| `prd-<slug>.md` | `docs/01-背景与需求/prd-user-signup.md` |
+| ADR（02，必要时）| `adr-<NNNN>-<slug>.md` | `docs/02-系统方案与架构/adr-0007-user-signup.md` |
+| 后端设计（04）| `<slug>.md` 或 `<slug>/index.md` | `docs/04-后端详细设计/user-signup.md` |
+| 前端 / 客户端（05）| `<slug>-<platform>.md` 或 `<slug>/<platform>.md` | `docs/05-前端客户端详细设计/user-signup-web.md` |
+| 集成（06，启用时）| pair 内 `<slug>.md` | `docs/06-集成对接/web-to-server/user-signup.md` |
+| 测试（07，启用 qa 时）| `<slug>.md` | `docs/07-质量与测试/test-plans/user-signup.md` |
+| 契约 | OpenAPI 路径 / event 名 与 slug 对齐 | `contracts/openapi/api.yaml#/paths/~1auth~1signup` |
+
+> 中文标题写在文件**内部**（H1）；文件**名**保持英文 slug，便于跨工具检索。
+
+### 6.2 关联检查（governance-lint，warning）
+
+`governance-lint` 扫描 `docs/01-背景与需求/prd-*.md`，对每个 `prd-<slug>.md` 检查：
+
+- `docs/02-系统方案与架构/adr-*-<slug>.md` 或 `docs/04-后端详细设计/<slug>*` 或 `docs/05-前端客户端详细设计/<slug>*`，**至少一处**存在
+- 否则产生 **warning**：`prd-<slug>.md exists but no design / ADR counterpart found`
+
+warning 不是 error——允许"有 PRD 但还没开始设计"的过渡状态；但提醒避免漏写。反向不检查（设计 / 测试 / 契约存在但 PRD 缺失是合法的）。
+
+### 6.3 何时**不**强求 slug
+
+- 跨多个特性的横切设计（如"全局错误码体系"）
+- 纯重构 / 性能优化（没有独立 PRD）
+- 角色目录（07-11、design）的非 feature 通用内容（如通用 runbook）
+
+## 7. 治理细则入口
+
+`docs/governance/` 承载从 AGENTS.md 拆出的专项规则（CI、安全、Git、资产、集成、ops/deploy、tools/scripts、checklist 等）。索引见 [`governance/README.md`](governance/README.md)。
+
+<% if (it.options.integrations) { %>## 7. 集成对接入口
+
+`docs/06-集成对接/` 已通过 `integrations=true` 启用。完整规则见 [`governance/integrations.md`](governance/integrations.md)。
+<% } else { %>## 7. 集成对接
+
+本仓库未启用 `integrations`。如果未来需要与外部仓库 / 团队对接（例如本仓库只做后端，前端在另一仓库），手动建立 `docs/06-集成对接/` 并参考 [`governance/integrations.md`](governance/integrations.md)。
+<% } %>

package/src/templates/docs-skeleton/files/arch-README.md

@@ -0,0 +1,18 @@
+# 02-系统方案与架构
+
+ADR（架构决策记录）、方案对比、架构提案的归属目录。
+
+## ADR 命名
+
+`adr-<NNNN>-<slug>.md`，例 `adr-0001-agents-md-layering.md`。编号从 0001 起递增。
+
+## ADR 生命周期
+
+1. 草案进 `docs/过程文档/drafts/<topic>-plan.md`
+2. 评审通过后归档到本目录为 `adr-<NNNN>-<slug>.md`
+3. 在草案文件顶部加"已采纳 → 见 ADR-XXXX"指针
+4. ADR 一旦合入，**不再修改**；后续变更通过新 ADR 取代或修订
+
+## AI 触达模式
+
+`mode: suggest`。已采纳的 ADR 视为历史决策；新 ADR 的发起由人主导（架构 / 技术负责人），AI 仅在相关变更时提示"可能需要新 ADR 或修订 ADR-XXXX"。

package/src/templates/docs-skeleton/files/arch-_ai-policy.yaml

@@ -0,0 +1,8 @@
+# AI 访问策略：docs/02-系统方案与架构/
+# 依据 ADR-0003 §4.3
+mode: suggest
+notes: |
+  ADR 是历史决策。本目录下：
+  - 已采纳的 ADR 一旦合入，不再修改；后续变更通过新 ADR 取代或修订
+  - 新 ADR 的发起由人主导（架构 / 技术负责人）
+  - AI 在相关变更时仅在 PR 描述中提示"可能需要新 ADR 或修订 ADR-XXXX"