@wneng/create-keel 0.3.0 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wneng/create-keel",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Scaffolder for Contract First + Vibe Coding projects (keel conventions)",
   "keywords": [
     "scaffold",

package/src/templates/ci-gitee/files/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+# Pull Request
+
+> 来自 keel scaffolder（@wneng/create-keel <%= it.scaffolderVersion %>）
+> 完整规则见 [`docs/governance/git-workflow.md`](../docs/governance/git-workflow.md)
+
+## 概述（What & Why）
+
+<!-- 一句话讲清楚这个 PR 改了什么、为什么 -->
+
+## 关联引用
+
+<!-- 至少填一项；契约 / 设计 / spec 三选一 -->
+
+- 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
+- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- spec：`.kiro/specs/<feature>/`（如适用）
+
+## 变更类型
+
+- [ ] feat — 新增能力
+- [ ] fix — 缺陷修复
+- [ ] docs — 文档变更
+- [ ] refactor — 重构（无行为变化）
+- [ ] chore — 维护性变更
+- [ ] spike — 临时探索（必须在合入前补齐契约 / 文档）
+
+## 自检清单（Pre-merge）
+
+完整 checklist 见 [`docs/governance/checklists.md`](../docs/governance/checklists.md)。最常踩的 5 个坑：
+
+- [ ] 改了 `contracts/` → `contracts/CHANGELOG.md` 已同步更新
+- [ ] 触了 on-demand 目录 → 用户已说出 trigger keyword（"更新部署手册" / "更新合规证据" / "更新宣发" / "更新设计稿"）
+- [ ] **未**直接写 `docs/11-市场与对外材料/published/` 或 `docs/10-合规与安全/evidence/`（read-only）
+- [ ] AI 生成代码 → commit 用 `feat(ai): ...` / `chore(ai): ...` 前缀；PR 打 `ai-generated` 标签
+- [ ] 改了 `docs/governance/<file>.md` → AGENTS.md §7 对应摘要已同步
+
+## CI
+
+- [ ] 本地 `npm test` / `mvn test` / `pytest` 等已通过
+- [ ] `governance-lint` 本地通过：`node tools/governance-lint/index.js --strict`
+- [ ] 没有提交 secret / 私钥 / 真实 PII
+
+## 影响范围
+
+<!-- 列出受影响的执行环境 / 模块 / 服务 -->
+
+- [ ] `server/`（后端）
+- [ ] `web/`（前端）
+- [ ] `mobile/`（移动端）
+- [ ] `miniapp/`（小程序）
+- [ ] `agent/`（桌面 / CLI）
+- [ ] `contracts/`（契约）
+- [ ] `deploy/` / `ops/`（部署 / 基础设施）
+- [ ] 仅 docs
+
+## 回滚预案
+
+<!-- 如果合入后发现问题，怎么回滚？哪些数据 / 配置需要清理？ -->
+
+## 备注 / 截图
+
+<!-- 可选 -->

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

@@ -1,18 +1,152 @@
+# Gitee Pipelines for <%= it.options.projectName %>
+#
+# Generated by `@wneng/create-keel` (Contract First + Vibe Coding).
+#
+# Gitee Pipelines and GitHub Actions speak different YAML dialects;
+# this file uses the documented `stages + jobs` shape supported by
+# Gitee. If your team migrates to GitHub Actions, regenerate with
+# `--ci github` instead of porting by hand.
+#
+# Each stage runs sequentially; jobs within a stage run in parallel.
+# Failure in any stage aborts the pipeline.
+
 name: ci
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
+
+stages:
+  - lint
+  - test
+  - scan
+
 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"
+  governance-lint:
+    stage: lint
+    image: node:20-alpine
+    script:
+      - |
+        if [ -f tools/governance-lint/index.js ]; then
+          node tools/governance-lint/index.js --strict
+        else
+          echo "tools/governance-lint/ not present; skipping"
+        fi
+
+  contract-lint:
+    stage: lint
+    image: node:20-alpine
+    script:
+<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>      - npx --yes @stoplight/spectral-cli lint contracts/openapi/api.yaml
+<% } %><% if (it.options.contract === 'rest+events' || it.options.contract === 'events-only') { %>      - |
+        if [ -f contracts/asyncapi/asyncapi.yaml ]; then
+          npx --yes @stoplight/spectral-cli lint contracts/asyncapi/asyncapi.yaml
+        fi
+<% } %>      - |
+        for s in contracts/**/*.schema.json; do
+          [ -e "$s" ] || continue
+          npx --yes ajv-cli compile -s "$s"
+        done
+
+<% if (it.options.backend === 'node') { %>  server-node:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd server
+      - npm ci
+      - npm run lint --if-present
+      - npm run typecheck --if-present
+      - npm test --if-present
+<% } %><% if (it.options.backend === 'java') { %>  server-java:
+    stage: test
+    image: maven:3.9-eclipse-temurin-21
+    script:
+      - cd server
+      - mvn -B verify
+<% } %><% if (it.options.backend === 'go') { %>  server-go:
+    stage: test
+    image: golang:1.22-alpine
+    script:
+      - cd server
+      - go vet ./...
+      - go test ./...
+<% } %><% if (it.options.backend === 'python') { %>  server-python:
+    stage: test
+    image: python:3.12-slim
+    script:
+      - cd server
+      - pip install -e .[dev] || pip install -e .
+      - ruff check .
+      - ruff format --check .
+      - pytest -q
+<% } %>
+<% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>  web:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd web
+      - npm ci
+      - npm run lint --if-present
+      - npm run typecheck --if-present || npx tsc --noEmit
+      - npm test --if-present
+      - npm run build
+<% } %>
+<% if (it.options.mobile === 'flutter') { %>  mobile-flutter:
+    stage: test
+    image: cirrusci/flutter:stable
+    script:
+      - cd mobile
+      - flutter pub get
+      - flutter analyze
+      - flutter test
+<% } %><% if (it.options.mobile === 'react-native') { %>  mobile-react-native:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd mobile
+      - npm ci
+      - npm run lint --if-present
+      - npm test --if-present
+<% } %>
+<% if (it.options.miniapp === 'wechat') { %>  miniapp-wechat:
+    stage: test
+    image: node:20-alpine
+    script:
+      - cd miniapp
+      - |
+        if [ -f tsconfig.json ]; then npx tsc --noEmit; else echo "no tsconfig"; fi
+<% } %>
+<% if (it.options.agent === 'rust-desktop') { %>  agent-rust:
+    stage: test
+    image: rust:1.78
+    script:
+      - cd agent
+      - cargo fmt --check
+      - cargo clippy --all-targets -- -D warnings
+      - cargo test
+<% } %>
+  secret-scan:
+    stage: scan
+    image: zricethezav/gitleaks:latest
+    script:
+      - gitleaks detect --redact --no-git -v
+
+<% if (it.options.backend === 'node' || it.options.frontend === 'react' || it.options.frontend === 'vue' || it.options.mobile === 'react-native' || it.options.miniapp === 'wechat') { %>  npm-audit:
+    stage: scan
+    image: node:20-alpine
+    script:
+<% if (it.options.backend === 'node') { %>      - cd server && npm audit --audit-level=high && cd ..
+<% } %><% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>      - cd web && npm audit --audit-level=high && cd ..
+<% } %><% if (it.options.mobile === 'react-native') { %>      - cd mobile && npm audit --audit-level=high && cd ..
+<% } %><% } %>
+<% if (it.options.backend === 'go') { %>  go-vulncheck:
+    stage: scan
+    image: golang:1.22-alpine
+    script:
+      - cd server
+      - go install golang.org/x/vuln/cmd/govulncheck@latest
+      - govulncheck ./...
+<% } %><% if (it.options.backend === 'python') { %>  pip-audit:
+    stage: scan
+    image: python:3.12-slim
+    script:
+      - cd server
+      - pip install pip-audit
+      - pip-audit
+<% } %>

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

@@ -1,5 +1,5 @@
 name: ci-gitee
-version: 1.0.0
+version: 1.2.0
 appliesWhen:
   ci: gitee
 priority: 20
@@ -7,3 +7,6 @@ files:
   - from: files/pipeline.yml
     to: .gitee/pipelines/ci.yml
     render: true
+  - from: files/PULL_REQUEST_TEMPLATE.md
+    to: .gitee/PULL_REQUEST_TEMPLATE.md
+    render: true

package/src/templates/ci-github/files/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,62 @@
+# Pull Request
+
+> 来自 keel scaffolder（@wneng/create-keel <%= it.scaffolderVersion %>）
+> 完整规则见 [`docs/governance/git-workflow.md`](../docs/governance/git-workflow.md)
+
+## 概述（What & Why）
+
+<!-- 一句话讲清楚这个 PR 改了什么、为什么 -->
+
+## 关联引用
+
+<!-- 至少填一项；契约 / 设计 / spec 三选一 -->
+
+- 契约锚点：`contracts/openapi/api.yaml#/paths/...` 或 `contracts/events/event-catalog.yaml#/events/...`
+- 设计文档：`docs/04-后端详细设计/<slug>.md` 或 `docs/05-前端客户端详细设计/<slug>-<platform>.md`
+- spec：`.kiro/specs/<feature>/`（如适用）
+
+## 变更类型
+
+- [ ] feat — 新增能力
+- [ ] fix — 缺陷修复
+- [ ] docs — 文档变更
+- [ ] refactor — 重构（无行为变化）
+- [ ] chore — 维护性变更
+- [ ] spike — 临时探索（必须在合入前补齐契约 / 文档）
+
+## 自检清单（Pre-merge）
+
+完整 checklist 见 [`docs/governance/checklists.md`](../docs/governance/checklists.md)。最常踩的 5 个坑：
+
+- [ ] 改了 `contracts/` → `contracts/CHANGELOG.md` 已同步更新
+- [ ] 触了 on-demand 目录 → 用户已说出 trigger keyword（"更新部署手册" / "更新合规证据" / "更新宣发" / "更新设计稿"）
+- [ ] **未**直接写 `docs/11-市场与对外材料/published/` 或 `docs/10-合规与安全/evidence/`（read-only）
+- [ ] AI 生成代码 → commit 用 `feat(ai): ...` / `chore(ai): ...` 前缀；PR 打 `ai-generated` 标签
+- [ ] 改了 `docs/governance/<file>.md` → AGENTS.md §7 对应摘要已同步
+
+## CI
+
+- [ ] 本地 `npm test` / `mvn test` / `pytest` 等已通过
+- [ ] `governance-lint` 本地通过：`node tools/governance-lint/index.js --strict`
+- [ ] 没有提交 secret / 私钥 / 真实 PII
+
+## 影响范围
+
+<!-- 列出受影响的执行环境 / 模块 / 服务 -->
+
+- [ ] `server/`（后端）
+- [ ] `web/`（前端）
+- [ ] `mobile/`（移动端）
+- [ ] `miniapp/`（小程序）
+- [ ] `agent/`（桌面 / CLI）
+- [ ] `contracts/`（契约）
+- [ ] `deploy/` / `ops/`（部署 / 基础设施）
+- [ ] 仅 docs
+
+## 回滚预案
+
+<!-- 如果合入后发现问题，怎么回滚？哪些数据 / 配置需要清理？ -->
+
+## 备注 / 截图
+
+<!-- 可选 -->

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

@@ -4,14 +4,207 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+
+# CI for <%= it.options.projectName %>
+#
+# Generated by `@wneng/create-keel` (Contract First + Vibe Coding).
+# Each job below is independent so a failure in one (e.g. server) does
+# not skip the others. The `governance-lint` and `contract-lint` jobs
+# are always present; per-environment jobs are conditionally included
+# based on the project's options.
+#
+# Tweak version pins / cache keys / extra steps freely; do not delete
+# governance-lint or contract-lint without an ADR.
+
 jobs:
-  checks:
+  governance-lint:
     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"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: governance-lint
+        run: |
+          if [ -f tools/governance-lint/index.js ]; then
+            node tools/governance-lint/index.js --strict
+          else
+            echo "tools/governance-lint/ not present; skipping"
+          fi
+
+  secret-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: gitleaks
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  contract-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+<% if (it.options.contract === 'rest' || it.options.contract === 'rest+events') { %>      - name: spectral lint (OpenAPI)
+        run: npx --yes @stoplight/spectral-cli lint contracts/openapi/api.yaml
+<% } %><% if (it.options.contract === 'rest+events' || it.options.contract === 'events-only') { %>      - name: spectral lint (AsyncAPI)
+        run: |
+          if [ -f contracts/asyncapi/asyncapi.yaml ]; then
+            npx --yes @stoplight/spectral-cli lint contracts/asyncapi/asyncapi.yaml
+          else
+            echo "no asyncapi.yaml; skipping"
+          fi
+<% } %>      - name: json-schema validate
+        run: |
+          shopt -s nullglob
+          for s in contracts/**/*.schema.json; do
+            npx --yes ajv-cli compile -s "$s"
+          done
+
+<% if (it.options.backend === 'node') { %>  server-node:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: server/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm run typecheck --if-present
+      - run: npm test --if-present
+      - name: dependency scan
+        run: npm audit --audit-level=high
+<% } %><% if (it.options.backend === 'java') { %>  server-java:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - run: mvn -B verify
+<% } %><% if (it.options.backend === 'go') { %>  server-go:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+      - run: go vet ./...
+      - run: go test ./...
+      - name: govulncheck
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          govulncheck ./...
+<% } %><% if (it.options.backend === 'python') { %>  server-python:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: server
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -e .[dev] || pip install -e .
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy . || true
+      - run: pytest -q
+      - name: pip-audit
+        run: pip install pip-audit && pip-audit
+<% } %>
+<% if (it.options.frontend === 'react' || it.options.frontend === 'vue') { %>  web:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm run typecheck --if-present || npx tsc --noEmit
+      - run: npm test --if-present
+      - run: npm run build
       - name: dependency scan
-        run: echo "npm audit / pip-audit / trivy"
+        run: npm audit --audit-level=high
+<% } %>
+<% if (it.options.mobile === 'flutter') { %>  mobile-flutter:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mobile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+      - run: flutter pub get
+      - run: flutter analyze
+      - run: flutter test
+<% } %><% if (it.options.mobile === 'react-native') { %>  mobile-react-native:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: mobile
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: mobile/package-lock.json
+      - run: npm ci
+      - run: npm run lint --if-present
+      - run: npm test --if-present
+<% } %>
+<% if (it.options.miniapp === 'wechat') { %>  miniapp-wechat:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: miniapp
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: typecheck
+        run: |
+          if [ -f tsconfig.json ]; then npx tsc --noEmit; else echo "no tsconfig"; fi
+<% } %>
+<% if (it.options.agent === 'rust-desktop') { %>  agent-rust:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: agent
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+      - run: cargo fmt --check
+      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo test
+<% } %>

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

@@ -1,5 +1,5 @@
 name: ci-github
-version: 1.0.0
+version: 1.2.0
 appliesWhen:
   ci: github
 priority: 20
@@ -7,3 +7,6 @@ files:
   - from: files/ci.yml
     to: .github/workflows/ci.yml
     render: true
+  - from: files/PULL_REQUEST_TEMPLATE.md
+    to: .github/PULL_REQUEST_TEMPLATE.md
+    render: true

package/src/templates/contracts-base/files/_spectral.yaml

@@ -0,0 +1,21 @@
+# Spectral lint config for OpenAPI / AsyncAPI contracts.
+#
+# Source of truth referenced by docs/governance/integrations.md.
+# CI runs `npx @stoplight/spectral-cli lint contracts/openapi/api.yaml`
+# and aborts on errors.
+
+extends:
+  - 'spectral:oas'
+
+rules:
+  # Make these MUST-have for keel projects.
+  operation-operationId: error
+  operation-tag-defined: error
+  contact-properties: warn
+  info-contact: warn
+  info-license: warn
+
+  # Don't enforce description on every parameter — too noisy on first
+  # commit. Re-enable per project once the API stabilises.
+  operation-description: off
+  operation-parameters: warn

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

@@ -1,5 +1,5 @@
 name: contracts-base
-version: 1.0.0
+version: 1.1.0
 appliesWhen: {}
 priority: 10
 files:
@@ -12,6 +12,9 @@ files:
   - from: files/CHANGELOG.md
     to: contracts/CHANGELOG.md
     render: false
+  - from: files/_spectral.yaml
+    to: contracts/.spectral.yaml
+    render: false
   - from: files/dictionaries/domain-models.yaml
     to: contracts/dictionaries/domain-models.yaml
     render: false

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

@@ -66,7 +66,7 @@ docs/
 | `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 |
+| `过程文档/` | `drafts/` + `meeting-notes/` + `spike-investigations/` | AGENTS.md §5 |
 
 ### 5.2 软建议（按项目实际调整）
 
@@ -125,10 +125,10 @@ warning 不是 error——允许"有 PRD 但还没开始设计"的过渡状态
 
 `docs/governance/` 承载从 AGENTS.md 拆出的专项规则（CI、安全、Git、资产、集成、ops/deploy、tools/scripts、checklist 等）。索引见 [`governance/README.md`](governance/README.md)。
 
-<% if (it.options.integrations) { %>## 7. 集成对接入口
+<% if (it.options.integrations) { %>## 8. 集成对接入口
 
 `docs/06-集成对接/` 已通过 `integrations=true` 启用。完整规则见 [`governance/integrations.md`](governance/integrations.md)。
-<% } else { %>## 7. 集成对接
+<% } else { %>## 8. 集成对接
 
 本仓库未启用 `integrations`。如果未来需要与外部仓库 / 团队对接（例如本仓库只做后端，前端在另一仓库），手动建立 `docs/06-集成对接/` 并参考 [`governance/integrations.md`](governance/integrations.md)。
 <% } %>

package/src/templates/docs-skeleton/files/governance-checklists.md

@@ -4,7 +4,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 # 完整检查清单
 
-> 入口摘要在 `AGENTS.md` §13。本文件提供完整可勾选清单。
+> 入口摘要在 `AGENTS.md` §9。本文件提供完整可勾选清单。
 
 ## 1. 开发前核对（功能开发启动前）
 
@@ -19,7 +19,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 ## 2. 提交前核对（PR 发起前）
 
 - [ ] `contracts/CHANGELOG.md` 已同步更新
-- [ ] 破坏性变更已按 §6 升级 MAJOR
+- [ ] 破坏性变更已按 [`contracts/README.md`](../../contracts/README.md) 的 SemVer 规则升级 MAJOR
 - [ ] 生成代码已重新生成且 `git diff` 为空
 - [ ] `docs/README.md` 已按需同步（目录地图 / 分类入口 / 子目录约定）
 - [ ] 若启用 `integrations` 且契约变更影响某 pair，该 pair 已同步
@@ -48,7 +48,7 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 ## 5. 新增脚本 / 工具核对
 
-- [ ] 已按 §12.3 判定归属（`scripts/` 或 `tools/`）
+- [ ] 已按 [`tools-scripts.md`](tools-scripts.md) 判定归属（`scripts/` 或 `tools/`）
 - [ ] `scripts/` 脚本顶部注释包含用途、参数、幂等性、危险级别
 - [ ] `scripts/README.md` 索引已更新
 - [ ] `tools/` 工具含独立 `README.md` 与版本号

package/src/templates/docs-skeleton/files/governance-security.md

@@ -10,8 +10,12 @@ last-reviewed: <%= it.generatedAt.slice(0, 10) %>
 
 ### 1.1 版本管理
 
-- 新增依赖使用**精确版本**（pinned），禁止开放范围
-- `package.json` / `requirements.txt` / `go.mod` / `Cargo.toml` / `pom.xml` 都遵循同一原则
+- **建议**新增依赖使用精确版本（pinned），尤其是安全敏感库（加密、token、SSO）
+- 实操中允许两种策略：
+  - **lockfile-based**（默认）：`package.json` 用 `^` 范围 + 提交 `package-lock.json` / `yarn.lock`，CI 跑 `npm ci`（严格按 lockfile）。Node / npm 生态的事实标准
+  - **fully-pinned**：`package.json` 用 `=` 精确版本。安全敏感项目或需要 SBOM 严格匹配时使用
+- 真值：lockfile（不是 `package.json`）。`package-lock.json` / `yarn.lock` / `pnpm-lock.yaml` 必须提交
+- 工程规范的 `tech-stack-<env>.md` 钉死表 + `governance-lint stack-pinning` 是更细粒度的版本守门（参见 ADR-0004）
 - 升级依赖独立 PR，便于回滚
 
 ### 1.2 漏洞扫描