# Changelog

All notable changes to this project will be documented in this file.

## [2.0.0] - 2026-10-14

### Breaking Change（升级前必读）

> 专题升级说明：[D-14-v2.0.0-功能发布说明.md](docs/D/D-14-v2.0.0-功能发布说明.md)（中文）/ [D-15-v2.0.0-Release-Notes-EN.md](docs/D/D-15-v2.0.0-Release-Notes-EN.md)（English）

本次为 **major** 升级：**生成侧产物的结构与校验口径变了**。已初始化的老项目升级后需按下列 3 项迁移（**未迁移不会静默出错**，`check-constitution` / `drift-check` 会显式报出）：

1. **门禁 `source` 形态变更**：由 `AGENTS#<章节名>` → `AGENTS#<红线 ID>[@<章节名>]`。旧形态仍可解析，但 `check-constitution` 规则 A' 记 `warning`（章节改名即静默断链）。
2. **新增必生成产物**：`docs/B/B-00-红线与门禁映射.md`（红线权威表）。**缺失时规则 A/E 双双降级**，违宪审查只剩"查僵尸门禁"一半；`check-constitution` 会输出降级事实 + 未覆盖风险两条 info。
3. **BUG 知识库 schema 收敛**：`### 模式 XX：` / `§2.NN 模式 XX` 两套写法**废止**，统一为 `## BUG-<NNN> | <标题>`。老项目未迁移时 `eval-baseline.md` 的「缺陷 → 门禁转化率」分母为 0（指标不可计算，不影响门禁）。

> 另有 1 项**不阻断**的行为变化：`docs/B/` 编号顺移一位（`B-03`→`B-04`、`B-04`→`B-05`、`B-05`→`B-06`、`B-06`→`B-07`），红线权威表占用新号 `B-00`。老项目按自身索引为准，无需强制改名。

### 生成侧缺陷清除（G1~G8：新项目初始化不再继承 PB 现有问题）

> 判定口径：只看「这条缺陷会不会被写进交付给新项目的产物」（`AGENTS.md` / `docs/` 骨架 / `scripts/gates.json` / `verify.*` / `check-constitution.*` / `docs-check.*` / `drift-check.*` / CI 配置 / git hooks）。BP 仓库自身的运维问题不计入。
> 复现方法：系统临时目录内建 3 个最小项目（① Node+测试框架 ② Node 无测试框架 ③ 纯文档）→ 按 `SKILL.md` → `references/step-1..7` 完整走一遍初始化 → 对产物逐条扫描。**未新建 test 框架**。

#### Fixed（生成侧）
- **G1｜CI 模板把「假绿开关」写进每个新项目**：`references/ci-template.yml` 三处 + `references/knowledge-base.md` 11 处 `--passWithNoTests` **全部清除**；test 步骤改造为**模板内带标记 + 按探测结果保留/删除**（标记 `# ↓ test 步骤：仅在 Step 1 探测到测试框架或测试文件时生成`），Go 的 `go test ./...` 无条件保留（语义不同）。实测根因：该参数让"零测试"判绿（`xiangmuces` 的 `.github/workflows/ci.yml` 即照此模板生成、且其审计结论原文即「因 spec 未入库，CI 实际空跑（假绿）」）。**"零测试判红"本就是 vitest / jest / mocha / pytest 的默认行为**，故修法是"删开关"而非"换开关"。
- **G2｜workflow 骨架不含门禁 job，只在文末给「追加片段」**：四种语言的**完整 workflow 已内联** `constitution` job（调用 `scripts/verify.*`），**取消"追加片段"步骤**；`step-5` 把"必须生成门禁 job"写成硬性规则 + 4 条生成后自检表。顺带修掉「模板引用不存在宿主」：`make verify` / `python scripts/verify.py` 原先没有任何实现，现补 **可运行的 `scripts/verify.py` 与 `scripts/check-constitution.py` 参考实现**（`references/verify-py-template.md` / `references/check-constitution-py-template.md`）与 Makefile 目标，并规定**未产出宿主不得在 CI 引用**。
- **G3｜种子门禁的 `source` 用章节名，改名即静默断链**：`source` 升级为 `AGENTS#<红线 ID>[@<章节名>]`（如 `AGENTS#RL-01@文档契约`），`<红线 ID>` 是权威引用、`@章节名` 仅供人读；旧形态仍可解析但记 `warning`（提示迁移）。新增**红线权威表** `docs/B/B-00-红线与门禁映射.md`（`RL-NN` append-only + 档位 + 对应门禁 + 无门禁原因），作为 `source` 的**唯一引用源**——AGENTS.md 只做索引，避免"AGENTS 一份清单 + gates.json 一份清单"的双份维护。
- **G4｜BUG 知识库 schema 在生成路径上有 4 种写法**：收敛为**唯一一种** `## BUG-<NNN> | <标题>`（三位补零/唯一/不复用）+ 症状速查表 + 六段式；`references/docs-skeleton.md` 的 B-04 行为 schema 唯一源，`ai-work-protocol.md`（条目内部结构）/ `step-3-docs.md`（生成模板）/ `project-sync-guide.md` / `eval-baseline.md`（计数口径）四处统一引用它。实测两套旧写法在真实项目上使 `eval-baseline` 的转化率分母**恒为 0**（`xiangmuces` 142 条 / `huichuangdazi` 60 条，按 `### 模式 ` 计数均为 0）。
- **G5｜「空转门禁」被播种给新项目**：`references/drift-check.mjs` ① 所有跳过分支改为输出**适用性裁定**（`检查 X 不适用｜原因：…｜风险：…｜裁定：本仓形态不适用`），不再裸"跳过"；② 无源码根时**回退到仓库顶层目录**比对（新增可编辑排除清单；"表里写了但路径不存在"→ warning，"目录存在但表里没有"→ info，避免对纯文档 / 小项目刷屏）。
- **G6｜「违宪审查」只装一半**：`check-constitution` 换用本仓已验证实现并新增**规则 E**「权威表中 `blocking` 档红线必须有 ≥1 条门禁引用」（原实现只查得出僵尸门禁，查不出"有红线无门禁"）；规则 A 升级为「红线 ID ↔ 权威表」双向定位；**权威表缺失时规则 A 定位失败降级为 warning**（不因"尚未建表"让新项目第一天就红），但必须输出**已降级事实 + 未覆盖风险**两条 info，禁止静默给出 `0 error`。**附修 G6-b**：生成侧模板原为 87 行 v1.0（规则只认 `[门禁:<id>]` 注解，而生成侧从不产出该注解 ⇒ 恒空跑、输出 `0 error / 0 warning / 0 info`），现替换为 311 行的 **规则 A / A' / B / C / D / E** 实现。
- **G7｜CI 模板没有「运行时自证」**：每个 job 的**首条命令**加 `command -v <runtime> || <分层自装>` + 版本打印。实测根因（`xiangmuces` `.workflow/ci.yml` 注释原文）：Gitee Go 插件未提供 `node`/`npm`，导致该 stage 5 条命令**全部** `command not found` 秒退、`CI 自建立起从未真正执行过任何一条门禁`。
- **G1 配套（新增检查 D）**：`drift-check` 新增「测试框架 ↔ CI test 步骤」漂移检查（探测到测试资产但 CI 无 test 步骤 → `warning`），防止"为了不复现假绿而干脆删掉 test 步骤"演变成新的静默缺陷。**负向验证**：删掉 CI 的 test 步骤 → 报出 warning；恢复后 → 通过。
- **G8 自查（用真实项目审计发现反查生成路径）**：另命中并处置 4 项 —— ① `eval-baseline.md` 引用已不存在的规则编号「规则 3」→ 改为规则 C；② 模板引用 `make verify` / `verify.py` 却无实现（并入 G2）；③ 文档引用的种子 `source` 与 AGENTS.md 生成模板不同源（并入 G3）；④ BUG 库编号语义漂移 `§2.NN`（并入 G4）。**未复现项**：对外数字口径（`95 组件 / 18 二级章节 / 16 维度` 全仓一致）、`40-60%`/`60,000+`/`76%` 在生成路径零命中 —— 均确认**不进生成物**，不处置。

#### Added（防复发的机器锚点）
- `references/eval-baseline.md` 新增 **§3.0 共同校验点（7 条，可机检）**：A1 生成物 `passWithNoTests` 命中数 = 0 / A2 CI 含 `scripts/verify.` 调用 / A3 每 job 首命令含 `command -v` + 版本打印 / A4 test 步骤与探测一致 / A5 权威表已生成且 `check-constitution` 0 error 且未降级 / A6 BUG 库 `^## BUG-` 计数口径一致 / A7 不静默跳过（禁裸"跳过"）。并明确 A1~A4 的**负向验证**要求。
- `references/eval-baseline.md` 新增两个关键形态：**§3.4 Node 项目（无测试框架）**（A1/A4 的关键形态）、**§3.5 纯文档项目（无源码根、无依赖清单）**（A5/A7 的关键形态），各含负向验证项。
- `references/verify-py-template.md` / `references/check-constitution-py-template.md`：Python 宿主可运行参考实现，**与 Node 版语义等价**（同一份 `gates.json` → 同一批门禁 → 同一退出码；实测 4 个场景输出一致）。

#### Changed
- `references/ci-template.yml` 重写为 v2.0：门禁 job 内联 + 运行时自证 + test 步骤带标记（无假绿开关）+ 4 条生成后自检表。
- `references/gates-templates.md` → v2.0：新增 §一之二 红线权威表；§三 规则表升级（含规则 E 与降级策略）；§五 收敛为薄索引 + 新增 §5.2/5.3/5.4 指向可运行 Python 宿主与 Makefile 目标；§8.2 补检查 D 与适用性裁定约定；§8.3 种子 `source` 改用 `RL-01` / `RL-02`。
- `references/drift-check.mjs`：新增检查 D、适用性裁定、顶层目录回退比对（+噪音排除清单）。
- `references/step-3-docs.md` Step 3.5 生成物清单新增红线权威表（与 `gates.json` **同时生成**）；`references/step-5-ci-and-gates.md` 规则改硬性并补生成后自检表；`SKILL.md` 输出验收清单拆为「门禁验收 5 条 + CI 验收 4 条」。
- `references/` 生成侧文件版本头统一标注为 **v2.0**（此前 6 个模板文件全部停在 `v1.0`，是 G6-b 代差的制度性成因）。
- `README.md` / `README_CN.md`：新增版本徽章与升级说明入口；核心能力表补「红线权威表 + 双向违宪审查」「门禁清单与统一入口（CI 内联 + 运行时自证）」；生成物清单补 `docs/B/B-00-红线与门禁映射.md` 并同步 `B-07`；独创特性表补 2 行（红线权威表双向审查 / CI 门禁内联 + 运行时自证）；数字口径（95 / 18 / 16 / 7 语言 15 框架）复核后保持一致。
- **文档编号**：红线权威表占用新号 `B-00`；`docs/B/` 原有编号顺移一位（`B-03`→`B-04`、`B-04`→`B-05`、`B-05`→`B-06`、`B-06`→`B-07`）；新增发布说明 `D-14`（中文）/ `D-15`（English）。

#### 验证（生成演练留证）
- 三个最小项目演练（临时目录，未入库）**修前 → 修后**：

  | 形态 | `passWithNoTests` | 含 `scripts/verify.` | 含 `command -v` | test 步骤 |
  |------|-------------------|----------------------|-----------------|-----------|
  | ① Node + Vitest + 测试文件 | 1 → **0** | 0 → **1** | 0 → **2** | 0 → **1** |
  | ② Node 无测试框架 | 1 → **0** | 0 → **1** | 0 → **2** | 0 → **0**（按标记删除） |
  | ③ 纯文档（无源码根/无依赖） | 0（无 CI） | 0（无 CI，已显式标注） | — | — |

- `drift-check` 在纯文档形态输出**适用性裁定**（`检查 A 不适用｜原因｜风险｜裁定`）、切回退模式并**确实在检**（报出"模块速查表写了 `src` 但路径不存在"）；对本仓自身 **0 warning**（无噪音刷屏）。
- 检查 D 双向负向验证：p1 删掉 CI test 步骤 → 报 warning；p2 临时加入 `vitest` → 报 warning；恢复后均归零。
- 规则 E 双向负向验证：权威表加一条无门禁的 `blocking` 红线 → 报 `存在红线却无门禁` error；`source` 引用不存在的 `RL-99` → 报 error；**Node / Python 两版输出一致**（4 场景逐一比对）。
- `node scripts/verify.mjs` 0 blocking 失败；`check-constitution` / `docs-check` / `drift-check` 均 0 error；`node dsh-plugin/scripts/sync-skill.mjs` 后根与副本 26 个文件 + `SKILL.md` 完全一致。
- 完整证据（含命令与输出）见 `internal-docs/D-13`（内部文档，不发布）。

#### 未闭环（发版时如实标注）
- 本仓库自身**尚未迁移到红线权威表**：`scripts/gates.json` 的 `source` 仍为旧形态 `AGENTS#<章节名>`，本仓的规则 A'/E 尚未真正生效（交付物已是新形态）。迁移排入下一步 `P3-14`。
- **Go / Vue / Python 三形态的 CI 产物未端到端演练**：本轮只做 Node（有/无测试）+ 纯文档三形态，三条 CI 改动对这三种语言仅有模板级与语法级验证。排入 `P3-15`。
- `references/gates-templates.md:305` 引用的行业数据（agent 配置文件 58% 单次提交 / 0.4 commits/月）**未标注来源**，属对外表述，另案处理。
- `references/monorepo-agents.md` 未加文件级版本头（其"版本头"是生成物模板内的占位符 `[YYYY-MM-DD]`，避免重复）。

---

### 上一批（同一周期）：外部评估复核 + 对外数字口径收敛 + 文档索引修复 + 机制可发表性交叉验证 + 门禁装配落地

> 复核报告与交叉验证见 `internal-docs/`（内部文档，不随公开仓发布）

### Added
- **外部评估复核**：内部复核报告已完成（含门禁脚本实跑、20+ 项数字口径核对、4 篇论文与 3 个外部站点独立复核；**文件名与结论不在公开仓描述**）
- 补登记 2 份内部文档入库（**不随公开仓发布**；此前仅为本地未跟踪文件，索引与实际文件不一致）
- **机制可发表性交叉验证（v2.0）**：内部报告由 v1.0 的「零件级对撞」改为**集成层口径**（8 环 × 6 个候选系统），并纳入元规则层；结合 `gate-audit` 首份实跑数据划定**样本使用边界**（区分「回溯提炼源」与「正向应用样本」，显式排除循环论证）与后续论文方向。v1.0 的零件级结论已废弃
- **门禁装配落地（本仓库首次真正接线）**：新增 `.github/workflows/verify.yml`（push / PR / 手动触发，复用同一入口 `--stage=ci`）；根 `package.json` 新增 `scripts.verify` / `scripts.verify:ci`（对齐宿主优先级「复用既有入口」）
- **门禁效果审计工具 `scripts/gate-audit.mjs`**（零依赖、只读、支持 `--repo=` / `--json`）：产出两份报告 —— ① **装配体检**：门禁脚本三态（磁盘存在 / git 落盘 / 入口接线），输出**落盘率**与**生效率**，并单列「被入口引用但未落盘」（这类脚本在 CI 与其他克隆上必然失效）；② **效果回溯（ITS 口径）**：以门禁首次提交日为干预点 T0，比对 BUG 知识库中含「复发」的记录日期，把每个缺陷模式判定为「门禁前复发」（门禁补对位置）/「门禁后复发」（**门禁有效性反例**）/ 未落盘无法判定 / 仅建议未实现

### Fixed
- **对外数字口径统一**（AGENTS.md「对外数字口径唯一源」）：组件数 `70+` 全部收敛为知识库实测口径 `95 个组件条目`（`README.md` / `README_CN.md` / `SKILL.md` / `AGENTS.md` / `PROJECT_STATUS.md` / 根 `package.json` / `dsh-plugin/package.json` / `dsh-plugin/plugin.json`）；业务类型数 `13 种` 收敛为知识库实测 `12 种`（口径 = `references/knowledge-base.md`「业务类型文档模式」章节 12 条）
- `docs/README.md` 索引中「更新速览 HTML」链接指向不存在的 `D-06-v1.9.0-更新速览.html`（实际文件名为 `v1.9.0-更新速览.html`）；已按索引口径重命名实际文件，链接恢复有效
- CHANGELOG v1.8.0「未闭环」条目勾销：v1.8.0 tag 已补打并双远程推送，见 [1.9.0] 段「发版」
- **门禁「声明与装配」不一致修复**（与 v1.9.0 修的 docs-check 假绿同族）：`scripts/gates.json` 声明 `stage: ["pre-push","ci"]`，但本仓库此前**无任何触发点**（无 `.github/workflows`、无 `.husky`/`.githooks`、无生效钩子、`package.json` 无 `scripts`），门禁只在手动敲命令时执行，`✅ 无 blocking 失败` 易被误读为「体系在守护」；已补 CI 装配点（`--stage=ci`），并在 AGENTS.md 4.6 显式标注「CI 已装配 / pre-push 未装配」
- **公开范围收敛（`docs/` 只保留对外内容）**：7 份内部文档（D-01 / D-03 / D-05 / D-07 / D-08 / D-09 + v1.9.0 更新速览 HTML）迁至受 `.gitignore` 约束的 `internal-docs/`，公开仓不再推送；`docs/README.md` 保留「编号预留」登记（满足 `docs-consistency` 编号连续性检查，避免门禁在 CI 上空转）；公开文件中指向被移出文档的链接改为纯文本。**注意**：迁移只切断未来推送，D-01~D-09 已存在于此前 commit 历史中，公开渠道仍可查阅

### 验证
- **门禁实跑**（真实执行，四脚本全绿）：

  ```bash
  node scripts/verify.mjs             # 共 2 条门禁，blocking 失败 0 / warn 失败 0
  node references/docs-check.mjs      # 0 error / 0 warning / 4 info
  node references/drift-check.mjs     # 0 error / 0 warning / 2 info
  node scripts/check-constitution.mjs # 0 error / 0 warning / 3 info
  ```

- **同步副本校验**（真实执行）：`node dsh-plugin/scripts/sync-skill.mjs` 后根 `SKILL.md` 与插件副本 SHA256 一致（`41c6d6cf…`）
- **口径残留检查**（真实执行）：对外文档（README / README_CN / SKILL / AGENTS / PROJECT_STATUS / `package.json` / `plugin.json`）中 `70+` 与 `13 种业务类型` 已 0 残留；历史快照文档（D-01 / D-03 / D-04 / D-05，其中 D-01 / D-03 / D-05 现位于 `internal-docs/`）与 CHANGELOG 历史条目按「历史快照不追改」原则保留原数字
- **门禁装配验证**（真实执行）：`npm run verify` 与 `npm run verify:ci` 本地均通过（与 `node scripts/verify.mjs` 同语义）；`.github/workflows/verify.yml` 语法解析通过；**GitHub Actions 首跑 success**（run #1 / commit `ef45df0` / 14s / `--stage=ci`），装配点已生效
- **门禁审计实跑（3 个真实仓库）**：生效率 66.7% / 62.5% / 0%，落盘率 100% / 68.8% / 0%。在一处存量项目上实测出两类此前未被发现的问题 —— **5 个门禁已被 CI 入口（`scripts/ci/verify.ps1`，24 步）引用但未入库**（在其他克隆与 CI 上必然失效）；**2 个门禁成立后同类缺陷仍复发**（BUG 知识库原文自述"第 N 次复发"）。BUG 知识库解析覆盖率 112/124 标题，定量明细与口径定义见内部文档

### 未闭环
- ~~GitHub 落后 Gitee 2 个 commit（`origin/main` = `8a9a819`，滞后的提交含 v1.9.0 中英发布说明与文档索引登记）~~ → **已闭环（2026-09-18）**：本轮全部变更已推送双远程，Gitee 与 GitHub 的 `main` 一致（`HEAD` = `gitee/main` = `origin/main`）；GitHub 直连偶发 21s 超时，重试后成功（命令：`git -c http.https://github.com.proxy= push origin main`）
- GitHub 仓库 description 仍为 v1.2.0 口径 `7 languages × 14 frameworks × 61 components`，需在 GitHub 侧更新（本机未安装 `gh` CLI、无 API 凭据，由维护者手动改）
- `references/docs-check.mjs` 的索引链接校验仅覆盖 `.md` 链接（正则 `/\]\(\.\/([^)]+\.md)\)/g`），`.html` 等非 `.md` 链接属门禁盲区，建议后续补门禁（详见 D-08 §5.6）
- **Gitee 远程无 CI**：`.gitee-ci.yml` 未创建（Gitee Go 语法与 GitHub Actions 不同，需按其文档另写），当前装配点只覆盖 GitHub 远程
- **pre-push 钩子未装配**：启用需本地执行 `git config core.hooksPath .githooks` 并落 `.githooks/pre-push`；本机 git 配置未由 agent 代改，按需由维护者启用

## [1.9.0] - 2026-09-14

> 主题：跨栈通用性与规范不漂移 —— SKILL.md 按 Step 拆分瘦身、Monorepo 嵌套 AGENTS.md、规范漂移门（第二条种子门禁）+ 仓库自吃狗粮
> 详细发布说明见 [D-06-v1.9.0-功能发布说明.md](docs/D/D-06-v1.9.0-功能发布说明.md)（中文）/ [D-06-v1.9.0-Release-Notes-EN.md](docs/D/D-06-v1.9.0-Release-Notes-EN.md)（English）
> 差距来源见 D-05 行业对标与体系完备性评估报告（内部文档，不随公开仓发布）（P0-1 / P0-2 / P0-3 / P1-4 / P1-5 / P1-6 / P2-8 / P2-9 / P2-10）

### Added
- **Monorepo 嵌套 AGENTS.md**：多子项目（≥2 个构建/清单文件）由「根单文件分块写入」升级为「根 `AGENTS.md`（全局约束 + 子项目索引表）+ 各子项目包级 `AGENTS.md`（包级规范）」，对齐 AGENTS.md 官方「就近原则 closest-file-wins」；单项目行为与 v1.8.0 一致（零变化）。新增参考文件 `references/monorepo-agents.md`
- **规范漂移门（第二条种子门禁）**：新增零依赖参考实现 `references/drift-check.mjs`（依赖 ↔ AGENTS.md 技术栈行 / 模块速查表 ↔ 实际目录 / 门禁有效性），并登记为种子门禁 `spec-drift`；种子门禁由 1 条（`docs-consistency`）升级为 **2 条**（`docs-consistency` + `spec-drift`）
- **知识库 5 域扩展（15 个组件条目）**：`references/knowledge-base.md` 新增 5 个维度章节并补齐 15 个组件条目（每条四段：Commands / Conventions / CI job / Gate）
  - AI/LLM 栈（4）：LangChain / LangGraph、LlamaIndex、pgvector、Ollama / vLLM（本地推理服务）
  - IaC 与云原生（3）：Terraform、Helm、Kubernetes manifest（kubectl / kustomize）
  - 可观测性（3）：OpenTelemetry、Sentry、Prometheus + Grafana
  - 数据工程（2）：dbt、Airflow
  - 原生移动（3）：Flutter、SwiftUI（Swift）、Jetpack Compose（Kotlin）
  - 现状：`knowledge-base.md` 917 行 / 18 个二级章节（16 个技术栈维度 + 通用段落 + 业务类型文档模式）/ 95 个组件条目（`### [组件名]`）
- **规范驱动开发六阶段**：新增 `references/spec-driven.md`（specify → plan → tasks → checklist → implement → verify，每阶段有产物与准入门槛；三件套模板；`checklist` 可转门禁，标注 `source: spec#<change-id>`）；`references/step-3-docs.md` 3.3 由「仅说明三件套格式」升级为六阶段流程；`references/docs-skeleton.md` / `references/project-sync-guide.md` 同步
- **工具私有增强层**：新增 `references/vendor-breadcrumbs.md`（工具能力矩阵 + Cursor `.mdc` glob 分层 / Claude Code hooks·subagents / Copilot instructions 分层模板 + 增量与防漂移条款）；Step 2 的 breadcrumbs 由「仅指向文件」升级为「基线 + 私有增强层」
- **量化评估基准**：新增 `references/eval-baseline.md`（规模指标 / 闭环指标 / 3 类 golden case 期望产物 / 已知不覆盖项）
- **本仓库自吃狗粮（scripts/ 门禁层）**：新增 `scripts/gates.json`（2 条门禁）+ `scripts/verify.mjs`（统一入口，支持 `--stage=`）+ `scripts/check-constitution.mjs`（宪法自校验 A~D 规则）

### Changed
- `SKILL.md` 按 Step 拆分：正文由 1012 行压缩为 **113 行索引层**（触发条件 / 执行原则 / Step 索引与按需加载表 / 输出验收清单 / 参考文件索引）；7 个 Step 细节迁至 `references/step-1-discovery.md` ~ `step-7-adaptive.md`（Step 5.5 门禁装配并入 step-5）；内容零丢失（原 78 个 `##`/`###` 标题 100% 可定位）
- `references/docs-check.mjs` 校验范围改为**自适应**：遍历 `docs/` 实际存在的子目录（排除 archive / dev / node_modules），缺失目录不再整块跳过；本仓库 `docs/D` 已被真实校验（不再是「5 条检查全部跳过」）
- 口径唯一化：索引 24/24 对齐、技术栈维度清单 11 → 16、组件条目层级统一 `### [组件名]`、`knowledge-base.md` 头注由「每个组件四段」改为准确表述（95 个组件条目中 27 个含 `**Gate**` 段）
- README / README_CN：核心能力表 +5 行（Monorepo 嵌套 AGENTS.md / 工具私有增强层 / 按需加载 / 规范驱动开发六阶段 / 规范漂移门）；生成内容一览 +`scripts/drift-check.*`、+「多子项目时各子项目目录下的 `AGENTS.md`」，更新 `scripts/docs-check.*`（校验范围自适应）与 `scripts/gates.json`（默认播种 2 条种子门禁）；技术栈覆盖表新增 5 个域行、汇总行更新为「18 个二级章节（16 个技术栈维度）+ 95 个组件条目」；工作流程补「Step 细节按需加载」与「多子项目 → 根 + 包级 AGENTS.md」分支，「15+ 文件」表述改为「多子项目时另生成各包级 AGENTS.md」；「与众不同之处」+3 条（规范不漂移 / Monorepo 就近覆盖 / 渐进式披露）
- `AGENTS.md`：模块速查表补 `scripts/` 门禁层与 4 个新参考文件 + 7 个 step 文件（合并一行）；强制规范补「`SKILL.md` ≤ 200 行 / `references/step-*.md` ≤ 500 行」与「对外数字口径唯一源」；关键架构决策表 +4 条；版本/日期更新为 v1.9.0 / 2026-09-14

### Fixed
- `AGENTS.md` 知识库条目层级表述错误：`## [组件名]` 更正为 `### [组件名]`（知识库实际为 `##` 维度章节 + `###` 组件条目）
- `references/docs-check.mjs` 文件头注释「首个门禁种子」更正为「种子门禁之一（docs-consistency）」（仅注释，逻辑未变）
- 新建 `docs/README.md` 文档索引（A~E 分类约定 + 维护规则 + D 级 5 条编号 / 7 篇文档登记），消除 `docs-consistency` 的最后 1 条 warning（「`docs/` 有文档但缺索引」）；索引内的相对链接可被门禁校验
- `docs/D/` 存量 4 篇文档补状态头（`D-01-代码规范闭环增强方案.md` / `D-02-v1.7.0-功能发布说明.md` / `D-02-v1.7.0-Release-Notes-EN.md` / `D-04-v1.8.0-Release-Notes-EN.md`），仅追加一行状态头，未改动既有内容；`docs-check` 存量 warning 由 5 条降至 1 条

### BREAKING
- **SKILL.md 文件结构重构**：正文由单文件拆分为 113 行索引层 + 7 个 `references/step-*.md` 细节文件（`references/` 文件数 12 → 24）。外部若有文档/脚本**按章节定位 `SKILL.md` 正文**，需改为指向对应 `references/step-*.md`（章节标题保持可定位，便于迁移）
- **多子项目场景生成物结构变化**：多子项目（≥2 个构建/清单文件）生成的根 `AGENTS.md` 由「包含各子项目规范分块」改为「**全局约束 + 子项目索引**」，各子项目规范改生成到各自目录下的 `AGENTS.md`（包级）
- 以上两项均为 **增量补充、不覆盖已有内容**；单项目场景行为与 v1.8.0 完全一致（零变化）

### 验证
- **规模校验**（真实执行）：`SKILL.md` = **113 行**（≤ 200）；step 文件行数：step-1-discovery 230 / step-2-assembly 159 / step-3-docs 293 / step-4-git 61 / step-5-ci-and-gates 68 / step-6-testing 131 / step-7-adaptive 89（均 ≤ 500）
- **文档一致性门禁**（真实执行，补状态头 + 补索引后）：
  ```bash
  node references/docs-check.mjs
  结果：0 error / 0 warning / 4 info   （exit 0）
  ```
  存量 warning 收敛过程（真实执行）：补状态头前 `0 error / 5 warning / 4 info`（4 篇 docs/D 缺状态头 + 缺 `docs/README.md` 索引）→ 补状态头后 `0 error / 1 warning / 4 info` → **新建 `docs/README.md` 索引后 `0 error / 0 warning / 4 info`**（索引覆盖关系已可校验：D 系列 5 条编号 7 篇文档全部被索引覆盖，索引内相对链接全部指向存在文件）
- **规范漂移门**（真实执行）：
  ```bash
  node references/drift-check.mjs
  结果：0 error / 0 warning / 2 info   （exit 0）
  ```
  （本仓库无依赖清单、无源码根，检查 A/B 输出 info；检查 C 门禁有效性在 `scripts/gates.json` 登记后生效）
- **门禁统一入口**（真实执行）：
  ```bash
  node scripts/verify.mjs
  结果：共 2 条门禁（blocking 失败 0 条 / warn 失败 0 条），耗时合计 298ms   （exit 0）
  ```
- **宪法自校验**（真实执行）：
  ```bash
  node scripts/check-constitution.mjs
  结果：0 error / 0 warning / 3 info   （exit 0）
  ```
- **负向验证**（真实执行并已还原）：临时创建 `docs/D/D-05-临时重复.md` → `docs-check` 报 `1 error`（编号冲突）exit 1；删除后恢复 `0 error` exit 0
- **代码围栏闭合校验**（真实执行）：`SKILL.md` 与全部 `references/*.md` 的行首三反引号计数均为偶数（无未闭合围栏）
- **同步副本校验**（真实执行）：`node dsh-plugin/scripts/sync-skill.mjs` 后，根 `SKILL.md` 与 `dsh-plugin/skills/project-blueprint/SKILL.md` SHA256 一致；`references/` 与插件副本的文件名集合一致（各 24 个）

- **发版**（真实执行）：commit `d90ded9` — `feat: v1.9.0 体系差距全量补齐 + v1.8.0 宪法层与门禁生长机制`（64 files changed, 8914 insertions(+), 1611 deletions(-)）＋发版记录 commit `8a9a819`；tag `v1.9.0`（`d655187`）与补打 tag `v1.8.0`（`23525ae`，与 v1.9.0 指向同一 commit）。双远程同步状态见「未闭环」

### 未闭环
- ~~本次改动未执行 `git commit` / `git push` / `git tag`~~ → **已发版并双远程同步（2026-09-14）**：commit `d90ded9`（+ 发版记录 `8a9a819`）；tag `v1.9.0`（`d655187`）与补打 tag `v1.8.0`（`23525ae`）；**Gitee 与 GitHub 的 `main` 均同步至 `8a9a819`，两个 tag 双远程均已推送**
- ~~GitHub tag `v1.9.0` 待补推（本机代理未运行、直连超时）~~ → **已闭环**：补推时一并完成 GitHub `main`（`d90ded9..8a9a819`）+ `v1.9.0` + `v1.8.0`（改用 `git -c http.https://github.com.proxy= push origin main v1.9.0 v1.8.0` 直连成功）
- ~~`docs-check` 仍有 1 条存量 warning（缺 `docs/README.md` 索引）~~ → **已闭环**：新建 `docs/README.md` 索引后复跑 `node references/docs-check.mjs` → `0 error / 0 warning / 4 info` exit 0（保留此行作为闭环记录）

## [1.8.0] - 2026-09-13

> 主题：宪法层与门禁生长机制 —— 把门禁从"初始化一次性产物"升级为"宪法驱动的生长物"
> 详细发布说明见 [D-04-v1.8.0-功能发布说明.md](docs/D/D-04-v1.8.0-功能发布说明.md)（中文）/ [D-04-v1.8.0-Release-Notes-EN.md](docs/D/D-04-v1.8.0-Release-Notes-EN.md)（English） | 评估报告见 D-03 真实项目文档体系优化引入评估报告（内部文档，不随公开仓发布）

### Added
- **宪法层元规则（写入 AGENTS.md）**：3 条元规则（无门禁不立规 / 缺陷必闭环 / 契约唯一源）+ 开工前置（读取 `scripts/gates.json`，新会话先了解本仓库现有门禁）；并配套三件套：门禁清单唯一事实源 `scripts/gates.json`、统一入口 `scripts/verify.*`、宪法自校验 `scripts/check-constitution.*`。元规则章节控制在 ≤ 15 行，细则一律外链，防宪法膨胀
- **门禁生长流程（6 步）**：① 触发 → ② 判定（准入门槛四问：可机检？零新依赖？真发生过？误报可控？）→ ③ 生成（三层递进取配方：跨语言门禁配方表 → 组件 `Gate` 段 → 联网搜索）→ ④ 注册（写具体检查 `scripts/checks/<id>.*` + `gates.json` 追加一条）→ ⑤ 验证（负向验证：故意制造违规确认门禁能拦住）→ ⑥ 登记（BUG 知识库 + 协议文档 + CHANGELOG）
- **门禁模板集 `references/gates-templates.md`**：`gates.json` 结构 / `verify.*` 统一入口 / `check-constitution.*` 宪法自校验 / 宿主与装配点选择 / 三版翻译要点
- **跨语言门禁配方表（10 条）+ 组件 `Gate` 第 4 段**：`references/knowledge-base.md` 通用段落新增 10 条语言无关门禁配方（契约漂移 / 硬编码密钥 / 锁文件一致 / 调试残留 / 静态检查 / 格式化 / 测试覆盖率 / 迁移与模型一致 / 文档一致性等）；组件条目格式由 3 段升级为 4 段（新增 `**Gate**`），12 个高频组件补齐 Gate 段
- **文档契约 + `docs-check` 校验脚本**：文档状态头（`> 版本: … | 更新: … | 状态: …`）/ 编号连续性 / 索引覆盖 / 归档冲突 + 单文件体积校验；输出分级 `error`（阻断）/ `warning`（不阻断）/ `info`（提示）；新增 `references/docs-check.mjs` 参考实现，作为首个门禁种子
- **AI 编程工作协议 `references/ai-work-protocol.md`**：7 步任务生命周期（读规范 → 查先例 → 定契约 → 列计划 → 实施 → 跑门禁 → 回写文档）/ 证据标准（改动给 `文件:行号`、验证给命令实际输出，禁止"应该没问题"）/ DoD 完成定义 8 条 / 违规处理表 / 缺陷复盘模板
- **SKILL.md 新增 Step 5.5「门禁装配」**：宿主选择（优先复用项目已有入口 → Node → Python → make → shell 兜底）+ 装配点（pre-commit / pre-push / CI）+ 生成后实跑自测 + `blocking` / `warn` 分级
- **按规模阈值触发**：小型项目只生成单条门禁（docs-check）+ 统一入口，不生成完整门禁层与协议文档，避免过度工程
- **仓库首次启用 spec 驱动开发**：`.trae/specs/implement-gate-constitution/`（spec.md / tasks.md / checklist.md 三件套）
- **新增 `docs/D/` v1.8.0 发布说明**（中文 [D-04-v1.8.0-功能发布说明.md](docs/D/D-04-v1.8.0-功能发布说明.md) + 英文 [D-04-v1.8.0-Release-Notes-EN.md](docs/D/D-04-v1.8.0-Release-Notes-EN.md)，中英互链，面向社区：为什么做 / 核心更新 / 差异速览 / BREAKING 与迁移 / 验证与未闭环）

### Changed
- `SKILL.md` 流程改造：新增 Step 5.5「门禁装配」；Step 2 新增宪法层注入（元规则 / 门禁清单与装配 / 规模硬阈值 / 文档契约）；Step 3 新增 3.5「门禁层与协议文档生成」+ 按规模阈值触发；Step 4 CHANGELOG 模板升级（「验证」/「未闭环」双节）；Step 5 新增门禁统一入口 job 与分级；Step 6.5 hooks 按语言选择；Step 7 新增门禁生长机制；输出验收清单同步更新
- `references/knowledge-base.md`：通用段落新增「跨语言门禁配方表」10 条；组件条目格式由 3 段升级为 4 段（新增 `**Gate**`）；12 个高频组件补 Gate 段
- `references/agents-md-template.md`：新增「九、门禁即规则（元规则）」「十、门禁清单与装配」；上下文管理新增规模硬阈值 / 文档契约 / 门禁生长登记；补齐缺失的 `> Reason:`
- `references/docs-skeleton.md`：新增 `B-06-门禁与工作协议.md`、`docs/issues/`、archive 归档登记表、文档契约章节；B-04 描述升级
- `references/project-sync-guide.md`：新增「门禁生长登记流程」「BUG 知识库升级要点」；何时同步表 +2 行；同步原则 +1 条
- `references/ci-template.yml`：新增「门禁统一入口 job」章节（Node/TS 完整示例 + Vue/Go/Python 等价写法）
- `docs/D/D-03-真实项目文档体系优化引入评估报告.md` v1.3：**源项目本机绝对路径脱敏**——33 处 `file:///d:/…` 链接前缀与 1 处头部路径统一替换为 `<源项目>` / `源项目/` 占位符，本仓库自身绝对路径改为相对链接；满足公开仓库不含本机路径的要求

### Fixed
- `references/knowledge-base.md` 数据库条目示例库名统一为占位符 `<db_name>`：MySQL 原写死 `app_db`、PostgreSQL 原用裸词 `dbname`，两者不一致且易被当作真实库名照抄；统一后与仓库既有占位符风格（`<pkg>` / `<entity>_id`）一致，符合「不写死项目特定信息」规范
  ```bash
  node dsh-plugin/scripts/sync-skill.mjs
  [sync-skill] synced SKILL.md + references/ -> dsh-plugin/skills/project-blueprint/
  ```
  校验：全仓 `grep -E "app_db|dbname"` → 0 匹配（根 `references/` 与 `dsh-plugin/skills/` 同步副本均已生效）

### BREAKING
- **SKILL.md 流程结构变更**：新增 Step 5.5「门禁装配」，Step 2 / 3 / 4 / 5 / 6.5 / 7 均有调整。既有用户重新初始化时，AGENTS.md 与 `docs/` 会多出章节与文件（**增量补充，不覆盖已有内容**）

### 验证
- **DSH 插件包技能内容同步**（真实执行）：
  ```bash
  node dsh-plugin/scripts/sync-skill.mjs
  [sync-skill] synced SKILL.md + references/ -> dsh-plugin/skills/project-blueprint/ (<repo>/dsh-plugin/skills/project-blueprint)
  ```
- **同步结果校验**（真实执行）：`dsh-plugin/skills/project-blueprint/references/` 文件数 = 12（含新增的 `ai-work-protocol.md` / `gates-templates.md` / `docs-check.mjs`）；根 `SKILL.md` 与 `dsh-plugin/skills/project-blueprint/SKILL.md` 均为 **50203 字节 / 1012 行**（内容行数，`newlines` 计数），SHA256 一致（`D0705F09…2B1482`）
- **SKILL.md 校验修复**（Task 7）：① 一处示例的硬编码年份改为 `{currentYear}` 占位符（符合「禁止硬编码年份」规范）；② 删除「注入 A」代码块中与协议/模板重复的一行，使元规则正文**三方（协议 / AGENTS 模板 / SKILL.md 注入块）逐字一致**；最终 50203 字节 / 1012 行
- **门禁脚本实跑**（真实执行）：`node --check references/docs-check.mjs` → exit 0；`node references/docs-check.mjs` → `结果：0 error / 0 warning / 5 info` + exit 0（本仓库无 `docs/B` 等目录时输出 info 并正常退出，不崩溃）
- **规格校验**（独立只读校验，分两轮）：发现的问题（元规则文本三方一致性、CHANGELOG 字节数过时、生长流程单边缺失、`references/` 硬编码年份残留、文件树口径遗漏）**已全部修复并复核通过**（详见 `.trae/specs/implement-gate-constitution/` 三件套；该目录为本地目录，受 `.gitignore` 约束，不随仓库发布）
- **发布前一致性审查**（2026-09-14，真实执行）：版本号三处一致（根 `package.json` / `dsh-plugin/package.json` / `dsh-plugin/plugin.json` 均为 1.8.0）；`SKILL.md` 与 `dsh-plugin/skills/` 副本逐字节一致（SHA256 `D0705F09…2B1482`）；`references/` 两侧各 12 个文件一致；全仓 Markdown 代码块闭合校验通过（无未闭合围栏）；相对链接可解析校验通过；`node references/docs-check.mjs` → `0 error / 0 warning / 5 info` + exit 0。**本轮修复 3 项**：① `docs/D/D-03` 状态头由"方案定案（尚未动手）"更正为"已实施"并补 §六「实施结果」实际范围；② `docs/D/D-03` §9.4 `gates.json` 示例由 `{version, gates}` 对象结构更正为**顶层数组**（与 `references/gates-templates.md` §一 实现口径一致）；③ 本文件「验证」段 `sync-skill` 输出中的本机绝对路径改为 `<repo>/` 占位符

### 未闭环
- ~~本次改动未执行 `git commit` / `git push` / `git tag`，未发布到 GitHub / Gitee 双远程~~ → **已闭环（2026-09-14）**：见 [1.9.0] 段「发版」——commit `d90ded9`；tag `v1.8.0`（`23525ae`，与 v1.9.0 指向同一 commit）双远程均已推送

## [1.7.1] - 2026-08-26

### Added
- **初始化流程生成 CHANGELOG.md**：SKILL.md Step 4 新增「CHANGELOG.md（如果没有则创建）」小节（[Unreleased] 初始化占位模板 + 增量跳过规则），输出验收清单补充 CHANGELOG.md 产物。修复「AGENTS.md 发布规范要求发版更新 CHANGELOG，但 skill 初始化不生成该文件」的不一致缺口

### Fixed
- **PROJECT_STATUS.md 版本演进表 v1.7.1 行丢失**（并发编辑竞态：后写覆盖先写，同 v1.7.0 记录过的 README 竞态问题）：已重补并逐行核对落盘。**对策**：同一文件的多个修改改为串行执行，每次修改后 Read/Grep 验证实际落盘

### Verified
- **DSH 0.1.1-rc.2 兼容性验证（2026-08-22）**：dsh 升级含破坏性变更（v0.1.0-rc.8 SQLite 会话存储格式不兼容、Session Projection API 迁移），实测 dsh-plugin **无需适配**——`ctx.skills.registerProvider` / `FileSystemSkillProvider` / `ctx.effect` 签名未变，`dsh.bundle.patch` 安装机制原样保留，隔离环境运行时验证通过（provider 成功发现 `project-blueprint` 技能）。详见 `dsh-plugin/README.md`「兼容性」

## [1.7.0] - 2026-08-14

> 详细发布说明见 [D-02-v1.7.0-功能发布说明.md](docs/D/D-02-v1.7.0-功能发布说明.md) | 方案见 D-01 代码规范闭环增强方案（内部文档，不随公开仓发布）

### Added
- **代码规范闭环增强**：初始化即实际写入基础代码规范（B-01 从占位符改为实写 8 章），AGENTS.md 强制规范含基础规范核心规则（≤20 条）
  - 新增 `references/code-conventions.md`：基础规范种子知识库（6 大类 × 语言适配，含搜索模板）
  - 新增 `references/ai-common-mistakes.md`：AI 高频错误知识库（7 大类 27 条，每条六段：AI 易错点/后果/❌示范/✅做法/关联知识库/搜索模板）
- **AI 高频错误防犯专项（最高优先级）**：Step 2 按技术栈优先注入 AI 易错点防犯规则；B-01 新增「AI 高频错误防犯清单」章节；代码审查清单新增 AI 高频检查项
- **BUG→规范反哺闭环**：B-04 模板新增「是否规范缺失/规范反哺」字段；修复规范缺失型 Bug 自动反哺更新 B-01 与 AGENTS.md；AI 犯错型 Bug 迭代 ai-common-mistakes 清单
- **项目进度与文档健康检查**：Step 7 注入按里程碑（功能完成/重构/上线/季度）检查文档滞后并提醒用户维护的机制
- SKILL.md Step 2 注入「代码规范体系」三层引用（AGENTS.md 核心 → B-01 详细 → B-04 反哺）
- `references/knowledge-base.md`：通用段落新增 AI 高频错误防犯原则 4 条（只走 happy path / 吞错误 / 硬编码密钥 / 写代码前先读现有代码），代码审查清单新增 AI 高频检查项 5 条（含"已对照 ai-common-mistakes.md 自查"）
- `references/docs-skeleton.md`：B-01 描述更新为实写 8 章（声明 AGENTS.md 为权威源、B-04 为反哺源），B-04 描述加入「规范反哺」字段说明
- agents-md-template.md 兜底模板新增 4.5 节（代码规范体系 + AI 高频错误防犯）
- README / README_CN：核心能力表 +2 行（基础代码规范实写 / AI 高频错误防犯）、生成内容补 B-01 实写说明、与众不同之处 +1 行、贡献指南 +2 行（基础规范库 / AI 易错点库）
- 新增 `docs/D/` v1.7.0 发布说明（中文 [D-02-v1.7.0-功能发布说明.md](docs/D/D-02-v1.7.0-功能发布说明.md) + 英文 [D-02-v1.7.0-Release-Notes-EN.md](docs/D/D-02-v1.7.0-Release-Notes-EN.md)，中英互链，面向社区）

### Fixed
- 初始化后 `docs/B/B-01-开发规范.md` 仅为占位符的问题（改为实写 8 章）
- README 双语文档并发编辑竞态导致新增能力行丢失（能力表 2 行 / 生成内容 B-01 说明 / 与众不同之处 1 行），已补齐并逐一复核
  - **原因**：同一文件多个并行写入互相覆盖（子代理内部并发 Edit 同一区域，后写覆盖先写）
  - **对策**：对同一文件的修改改为串行执行；每处修改完成后用 Grep/Read 验证实际落盘，不依赖子代理自报

## [1.6.1] - 2026-08-14

### Fixed
- **DSH 插件 GitHub 安装路径修复**：仓库根目录新增 `package.json`（声明 `dsh.bundle.patch: ./dsh-plugin/cordis.patch.yml` + `main: ./dsh-plugin/lib/index.js`），`dsh plugin --profile web add 'github:shuguang1994/project-blueprint'` 此前因根目录无 package.json 被 dsh 判定为普通依赖（`declares no dsh.bundle`）而无法激活；修复后 bundle 正确合成进 profile，社区安装命令直接可用
- 本地实测通过：以根目录包装形式安装 → `dsh --profile web --dump-config` 出现 `# == project-blueprint` bundle 层 → 重启 `dsh web` 运行正常
- `dsh-plugin/package.json` 版本 1.5.0 → 1.6.0（与项目版本一致）

## [1.6.0] - 2026-08-14

### Added
- **DSH (DeepSeek Harness) 插件支持**：新增 `dsh-plugin/` 自包含插件包，可将 Project Blueprint 一键安装到 DeepSeek Harness（2026-08-13 开源的 "一切皆插件" Agent 框架）
  - `package.json` + `cordis.patch.yml`：`dsh plugin --profile web add 'github:shuguang1994/project-blueprint'` 安装，复用官方 `@deepseek-ai/dsh-skill-filesystem` 提供方，零构建、零运行依赖、纯 Markdown 技能内容
  - `lib/index.js`：极简 ESM 插件（`import.meta.url` 定位包内 skills 目录，注册 custom skill 根，rank 300），无 TS 构建链
  - `plugin.json`：Agent Plugins v1.0.0 便携清单（跨宿主分发，同一份技能资源可被 Claude Code / Cursor / Codex 等客户端复用）
  - `scripts/sync-skill.mjs`：根目录 `SKILL.md` + `references/` 同步到插件包（单一事实来源 = 仓库根）
  - 本地实测通过：在 Cordis 运行时中挂载真实插件代码，`ctx.skills.list()` 发现 `project-blueprint`（provider=custom），`ctx.skills.get()` 完整加载 SKILL.md 正文
- README / README_CN 新增 dsh 安装方式；支持的 Agent 数量 27+ → 28+（新增 DeepSeek Harness）
- GitHub 仓库打 14 个 Topics 标签（dsh-plugin / dsh / deepseek-harness / agent-skills / skills / spec-driven / harness-engineering / coding-conventions / scaffolding / ai-coding / claude-code / cursor / codex / opencode）；README / README_CN 顶部新增 Topics 徽章行（点击跳转 GitHub 话题页）

## [1.5.0] - 2026-08-01

### Added
- **MCP 工具推荐能力**：Step 3 新增 3.4 子步骤，基于探测技术栈三层递进匹配 MCP 工具，生成 `docs/B/B-05-MCP工具清单.md`（推荐清单 + 组合矩阵 + 安装命令），供后期按文档安装
  - 新增 `references/mcp-tools.md`：MCP 工具知识库（10 维度 18 条目，三段式 适用场景/安装方式/推荐组合 + 维度匹配表 + 组合矩阵）
  - 双层联网保障：建库期条目安装命令必须 WebSearch 核对当前版本；推荐期第 3 层联网兜底未知工具；B-05 文档提示安装前联网核对
  - 仅生成 MD 文档，不写入项目级 `.mcp.json`（最小侵入）
  - docs-skeleton B/ 新增 B-05 行；project-sync-guide 同步操作表新增「新增/移除 MCP 工具」触发行
  - AGENTS.md 代码审查清单新增 mcp-tools.md 三段式检查项

### Fixed
- SKILL.md Step 3.4 三层递进第 1/2 层与 mcp-tools.md 分层标注对齐（第 1 层 = 工具条目「适用场景」精确匹配，第 2 层 = 「维度 → 工具匹配」表启发）
- README_CN「与众不同之处」语言数 8 → 7 统一（知识库实际 7 个语言条目，TS/JS 合并）
- README_CN 技术栈覆盖表末行 `<br />` 残留清理
- .gitignore 追加 `.trae/`（IDE 本地目录，避免误提交）
- PROJECT_STATUS 移除内部项目引用与本机绝对路径（开源仓库不暴露其他项目信息）

## [1.4.1] - 2026-08-01

### Added
- 通用规范新增「第三方库使用」规则：涉及第三方库（NestJS/TypeORM/BullMQ/Vant 等）的 API/版本/配置时，先查官方文档确认当前版本用法再写代码
  - knowledge-base 核心开发原则新增该约定（含升级依赖后核对破坏性变更）
  - agents-md-template 强制规范新增 4.4 节
  - 代码审查清单（knowledge-base + agents-md-template）新增「第三方库用法已核对当前版本文档？」检查项

### Fixed
- SKILL.md 流程描述「6 步」修正为「7 步」（实际为 Step 1~7）
- Step 4 分支策略改为按已有分支自适应（支持 main + tag 发布），不再强制新建 develop
- README/README_CN 数字核对：语言 8→7、通用规范 6→4，覆盖表总数按实际条目核算（79 组件）
- ci-template.yml / knowledge-base Git 规范 / agents-md-template 分支策略同步支持 main

## [1.4.0] - 2026-07-18

### Changed — BREAKING: Step 1 自主发现引擎重构

**Step 1.1 自主文件发现**：从「固定 12 种文件检查」改为「扫描→分类→推断」模式
- 新增文件发现策略：扫描项目所有文件，按 30+ 种文件名模式自动分类
- 新增项目结构推断：自动识别前后端分离（2/3 层）、monorepo、单项目
- 扩展文件覆盖：.csproj、composer.json、vite/next/nuxt/svelte/webpack/tailwind 配置、.env.example、Makefile、nginx.conf 等

**Step 1.2 智能依赖分类**：从「~35 条固定映射表」改为「三层递进分类引擎」
- 第 1 层：知识库精确匹配（快速通道，置信度 exact）
- 第 2 层：命名模式启发推断（29 种模式覆盖 100+ 依赖关键词，置信度 heuristic）
- 第 3 层：联网搜索（真正未知的依赖，置信度 web）
- 分类结果附带置信度标记，便于后续审查

**Step 1.3-1.4**：输出格式改为分项目块 + 置信度统计；多子项目独立探测

**Step 3.0 业务类型推断**：从「固定 8 类」改为「三层推断」
- 第 1 层：结构特征匹配（8 类）
- 第 2 层：配置特征启发推断（新增 CLI/库/SDK/桌面/静态站点 5 类）
- 第 3 层：联网搜索 + 类型优先级规则

**Step 6.3 测试示例**：从「固定 5 框架代码块」改为「3 级自主获取策略」
- 第 1 优先：快速参考表（12 框架，命中即用）
- 第 2 优先：knowledge-base 提取
- 第 3 优先：WebSearch 联网获取

## [1.3.0] - 2026-07-18

### Added
- 模块速查表联网回退：陌生目录/文件模式自动 WebSearch 推断职责，不再简单标记"待补充"
- Step 1.2 未知依赖标记 + 联网流向指引：不在映射表的 dep key 自动进入 Step 2.2 搜索
- 13 种文件模式 → 模块职责映射表（controller/service/repository/entity/handler/dto/gateway/job/middleware 等）
- 4 种模块推断联网搜索模板（陌生目录名/陌生文件后缀/架构模式关键词/英文业务术语）
- 全栈项目业务类型识别规则
- NestJS/React/Go Gin/FastAPI/Spring Boot 框架自适应测试模式（写入测试指南，非创建文件）

### Changed
- Step 2.2 联网回退扩展：从 4 维度（框架/ORM/测试/构建工具）扩展为 10 维度全覆盖（语言/CSS/Lint/包管理/状态管理/部署/数据库）
- Step 3.2 模块速查表改为 5 级推断流程（文件列表→模式匹配→联网搜索→标记待补充→写入）
- Step 3.0 后端检测覆盖非 Prisma 项目（controllers/modules/services 目录 + 后端框架 + ORM 配置）
- Step 4 git add -A 改为 git add . + 提交前检查有无变更
- Step 6 pre-commit hook 仅 JS/TS 项目执行，其他语言跳过
- README 框架列表与 knowledge-base 对齐（Fastify→Laravel+Hono；Actix-web 待补）
- README/README_CN 代理支持数量统一为 27+
- **Step 6 重设计**：不再强制创建 `assert true` 示例测试文件，改为生成 `docs/B/B-03-测试指南.md` 测试制度文档（含分层策略、按阶段的编写时机、框架自适应的测试模式示例）
- **Step 1 探测增强**：新增 `manifest.json`/`pages.json`（uni-app）、`ecosystem.config.js`（PM2）文件检测
- **Step 1.2 新增 UI 组件库维度**：Ant Design Vue / Element Plus / Naive UI / Arco Design / TDesign / Vant
- **knowledge-base 扩展**：uni-app 框架、UI 组件库层（4 条目）、NestJS 生态增强（swagger/schedule/event-emitter/winston）
- **Step 1.0 增量模式细化**：按 AGENTS.md 质量分 3 级处理（完善→检查缺失 / 部分缺失→补充 / 无→全量生成）

### Fixed
- **BUG**: knowledge-base.md 代码审查清单代码块未闭合，导致「业务类型文档模式」「模块速查表生成规则」两个完整章节被当作代码渲染
- **BUG**: SKILL.md Step 2.1 组件循环遗漏 包管理/部署/数据库 3 个维度，导致对应知识库条目不会被查找
- **BUG**: docs-skeleton.md 文件数量/名称与 SKILL.md Step 3.1 不一致（A:7→5, B:5→4, C:4→3, E:2→1）

## [1.2.0] - 2026-07-18

### Added
- 自适应探测引擎：10 种项目文件并行探测（package.json / go.mod / requirements.txt / pom.xml / Cargo.toml / Gemfile / tsconfig.json / docker-compose.yml / .eslintrc / .prettierrc）
- 61 组件知识库 `references/knowledge-base.md`（7 语言 / 14 框架 / 6 ORM / 5 CSS / 6 测试 / 15 Lint+包管理+部署 + 通用段落）
- 规则引擎拼接 AGENTS.md（按探测的组件从知识库动态拼接）
- 联网回退：未知技术栈自动触发 WebSearch 获取最新最佳实践

### Removed
- **BREAKING**: 删除固定预设目录 `references/presets/`（7 个语言预设），改为动态组件拼接

## [1.1.0] - 2026-07-18

### Added
- 6 技术栈预设：Next.js / Vue 3 + Vite / React + Vite / Go + Gin / Python + FastAPI / Java + Spring Boot
- Vendor breadcrumbs：自动生成 CLAUDE.md、.cursor/rules/project.mdc、.github/copilot-instructions.md
- CI 模板多语言支持（GitHub Actions / Gitee Go）

## [1.0.0] - 2026-07-18

### Added
- 初始版本：6 步规范体系搭建流程
- AGENTS.md 自动生成（150-200 行，4 核心章节）
- docs/ 文档骨架（A/B/C/D/E 五分类）
- Git 配置（.gitignore + 分支策略 + 首次 commit）
- CI/CD 配置（GitHub Actions 最小化 tsc 检查）
- 测试基础设施（框架安装 + 示例测试 + husky pre-commit hook）