stack-wuh · Oct 10, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026 · Oct 9, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "shadow-dev-workflow",
-  "description": "Self-contained development workflow with 3-tier knowledge base — 4-phase pipeline (propose → apply → review → ship) with packaged planning, TDD, verification, and knowledge-driven design constraints. Zero external workflow dependencies.",
-  "version": "6.5.1",
+  "description": "Self-contained development workflow with 3-tier knowledge base — 5-phase pipeline (propose → apply → review → release → archive) with packaged planning, domain-model-driven specs, invariant-based verification, and knowledge-driven design constraints. Zero external workflow dependencies.",
+  "version": "6.8.0",
   "author": {
     "name": "Shadow (stack-wuh)"
   },

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "shadow-dev-workflow",
-  "version": "6.5.1",
-  "description": "Self-contained development workflow with 3-tier knowledge base — propose → apply → review → release → archive with packaged planning, TDD, verification, and knowledge-driven design constraints. Zero external workflow dependencies.",
+  "version": "6.8.0",
+  "description": "Self-contained development workflow with 3-tier knowledge base — propose → apply → review → release → archive with packaged planning, domain-model-driven specs, invariant-based verification, and knowledge-driven design constraints. Zero external workflow dependencies.",
   "author": {
     "name": "Shadow (stack-wuh)",
     "url": "https://github.com/stack-wuh"
@@ -13,7 +13,7 @@
     "workflow",
     "skills",
     "knowledge-base",
-    "tdd",
+    "domain-driven",
     "planning",
     "code-review",
     "release",
@@ -24,7 +24,7 @@
   "interface": {
     "displayName": "Shadow Dev Workflow",
     "shortDescription": "Knowledge 驱动的开发工作流五段式管线",
-    "longDescription": "以 active Knowledge 驱动的 propose → apply → review → release → archive 工作流：需求对齐产出 brief、按 brief 执行 TDD 与依赖调度、质量门禁验收、知识闭环后提交发布 PR、合并后归档并重建 INDEX。另含 hotfix 快车道、知识库查询与 UI 设计提案伴侣。",
+    "longDescription": "以 active Knowledge 驱动的 propose → apply → review → release → archive 工作流：需求对齐做领域对齐（限界上下文与不变量）并产出 brief、按 brief 以不变量观察点执行分级验证与依赖调度、质量门禁验收模型一致性、知识闭环后提交发布 PR、合并后归档并重建 INDEX。另含 hotfix 快车道、知识库查询与 UI 设计提案伴侣。",
     "developerName": "Shadow (stack-wuh)",
     "category": "Coding",
     "capabilities": ["Read", "Write"],

diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml
@@ -0,0 +1,107 @@
+name: publish-release
+
+# 版本与产物的唯一权威发布点：GitHub Release tag 说了算。
+# tag ≠ package.json.version 直接判红（历史上「发版漏同步」出血两次），产物资产名必须匹配 CLI 侧解析正则，
+# 上传后立刻用真实 CLI 在隔离 prefix 里走完 plan → execute → bind，证明「传上去的东西真能被装上」。
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: publish-release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: publish ${{ github.ref_name }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout the tagged tree
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: 版本权威判定（release tag == package.json.version）
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -pe 'require("./package.json").version')
+          if [ "$TAG" != "$PKG" ]; then
+            echo "✗ release tag v$TAG 与 package.json.version $PKG 不一致——版本权威即失效"
+            echo "  修正：node scripts/bump-version.mjs $TAG && npm run check:version，重新提交后再打 tag 发布"
+            exit 1
+          fi
+          echo "✓ 版本权威成立：v$TAG"
+          npm run check:version
+
+      - name: Install pinned shadow-dev CLI
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          PIN=$(node -pe 'require("./package.json").cliVersion')
+          bash scripts/install-cli.sh install --version "$PIN"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          # 同 quality-gate.yml：$GITHUB_PATH 对后续步骤生效，本步内紧接着的冒烟需自带 PATH（当前 job 跑 ubuntu，防御性对齐，避免两条流水语义漂移）。
+          export PATH="$HOME/.local/bin:$PATH"
+          shadow-dev --version
+
+      - name: 发布前全门（version + requires:strict + knowledge + test）
+        shell: bash
+        run: |
+          npm run check:requires:strict
+          npm run check:knowledge -- --forbid 'tdd-verification,▶ [TDD]'
+          npm test
+
+      - name: Pack artifact
+        shell: bash
+        run: |
+          ART=$(node scripts/pack.mjs | tail -1)
+          echo "artifact=$ART"
+          echo "artifact=$ART" >> "$GITHUB_OUTPUT"
+          echo "basename=$(basename "$ART")" >> "$GITHUB_OUTPUT"
+        id: pack
+
+      - name: 资产契约断言（CLI 只认 shadow-dev-workflow-v<semver>.tar.gz）
+        shell: bash
+        env:
+          BASENAME: ${{ steps.pack.outputs.basename }}
+        run: |
+          node -e 'const n=process.env.BASENAME||"";const C=/^shadow-dev-workflow-v[0-9][0-9.]*\.tar\.gz$/;if(!C.test(n)){console.error("x asset name ["+n+"] violates CLI contract "+C);process.exit(1)}console.log("OK asset contract: "+n)'
+
+      - name: Upload asset to release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ARTIFACT: ${{ steps.pack.outputs.artifact }}
+        run: gh release upload "$GITHUB_REF_NAME" "$ARTIFACT" --clobber
+
+      - name: 发布冒烟（隔离 prefix：plan --release → execute → bind plan）
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          SMOKE="$RUNNER_TEMP/publish-smoke"
+          rm -rf "$SMOKE"; mkdir -p "$SMOKE/prefix" "$SMOKE/home"
+          export SHADOW_WORKFLOW_PREFIX="$SMOKE/prefix" SHADOW_WORKFLOW_HOME="$SMOKE/home"
+          shadow-dev workflow plan --release "$GITHUB_REF_NAME" --json | grep '^{"ok"' | tail -1 > "$SMOKE/plan.json"
+          node -e 'const d=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(!d.ok){console.error("plan failed: "+JSON.stringify(d.error));process.exit(1)}console.log("OK plan version="+d.data.version+" missing="+JSON.stringify(d.data.missingCommands))' "$SMOKE/plan.json"
+          HASH=$(node -pe 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).planHash' "$SMOKE/plan.json")
+          shadow-dev workflow execute --release "$GITHUB_REF_NAME" --plan-hash "$HASH" --confirm --json | grep '^{"ok"' | tail -1 > "$SMOKE/exec.json"
+          node -e 'const d=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(!d.ok){console.error("execute failed: "+JSON.stringify(d.error));process.exit(1)}console.log("OK execute current="+d.data.current)' "$SMOKE/exec.json"
+          CUR=$(node -pe 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).data.current' "$SMOKE/exec.json")
+          ROOT="$SMOKE/prefix/$CUR/shadow-dev-workflow"
+          test -f "$ROOT/norms/verification.md" || { echo "x materialized artifact missing norms/verification.md"; exit 1; }
+          N=$(find "$ROOT/skills" -name SKILL.md | wc -l | tr -d ' ')
+          [ "$N" = "8" ] || { echo "x materialized skills count=$N expected 8"; exit 1; }
+          echo "OK materialized root=$ROOT skills=$N"
+          shadow-dev bind plan --host codex --prefix "$SHADOW_WORKFLOW_PREFIX" --json | grep '^{"ok"' | tail -1 > "$SMOKE/bind.json"
+          node -e 'const d=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));if(!d.ok){console.error("bind plan failed: "+JSON.stringify(d.error));process.exit(1)}const x=d.data;console.log("OK bind plan host-version="+x.version)' "$SMOKE/bind.json"
diff --git a/.github/workflows/quality-gate.yml b/.github/workflows/quality-gate.yml
@@ -0,0 +1,59 @@
+name: quality-gate
+
+# 机器门：本仓所有可离线判定的断言都在这儿跑，AI 与人的口头自证不可替代它。
+# 覆盖：版本同源 → 能力一致性（strict，禁止半绿）→ 知识治理（卡片/source/路由/死链/残留）→ 产物与安装器测试。
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-gate-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: gate (${{ matrix.os }} / node ${{ matrix.node }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: ['20', '22']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+
+      - name: Install pinned shadow-dev CLI
+        shell: bash
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          PIN=$(node -pe 'require("./package.json").cliVersion')
+          bash scripts/install-cli.sh install --version "$PIN"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          # $GITHUB_PATH 只对后续步骤生效；同一步内紧接着的冒烟必须自带 PATH，
+          # 否则 windows-latest（Git Bash 默认不含 ~/.local/bin）判红而 ubuntu/macos 靠镜像默认值蒙过。
+          export PATH="$HOME/.local/bin:$PATH"
+          shadow-dev --version
+
+      - name: 版本同源门
+        run: npm run check:version
+
+      - name: 能力一致性门（strict：命令目录不可解析即判红，禁止降级半绿）
+        shell: bash
+        run: npm run check:requires:strict
+
+      - name: 知识治理门（卡片字段 / source / menu 路由 / 死链 / 废弃残留）
+        shell: bash
+        run: npm run check:knowledge -- --forbid 'tdd-verification,▶ [TDD]'
+
+      - name: 产物与安装器测试
+        run: npm test
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -7,6 +7,7 @@
 - `skills/`：定义 propose、apply、review、release、archive 和 Knowledge 查询流程。
 - `norms/`：跨项目硬规则与工程规范。
 - `knowledge/`：跨项目经验与协作知识。
+- 项目 `shadow-docs/domain.md`：限界上下文地图与统一语言（格式见 `norms/domain-model.md`）。
 - 项目 `shadow-docs/knowledge/`：项目独有的执行真相。
 - `menu.md` 与项目 `shadow-docs/menu.md`：任务到规范和 active Knowledge 的路由。
 - `brief.md` 与 INDEX：变更记录和历史索引，不覆盖 active Knowledge。
@@ -16,9 +17,9 @@
 | 位置 | 内容 |
 |------|------|
 | `rules/behavior.md` | 行为准则 |
-| `rules/iron-laws.md` | TDD、验证、调试、分支和 deterministic CLI 铁律 |
+| `rules/iron-laws.md` | 验证、调试、分支、deterministic CLI 和领域模型铁律 |
 | `norms/knowledge-cards.md` | Knowledge 卡片格式、生命周期和冲突处理 |
-| `norms/*.md` | UI、API、交互、代码风格和验证规范 |
+| `norms/*.md` | UI、API、交互、代码风格、领域模型和验证规范 |
 | `knowledge/*.md` | 跨项目经验与协作知识 |
 
 项目外 memory 不是工作流执行真相源。
@@ -45,6 +46,19 @@
 | Knowledge 查询 | `shadow-dev-knowledge`（propose 自动调用） |
 | 线上急修、紧急修复、hotfix | `shadow-dev-hotfix`（快车道，准入判定见其 SKILL.md） |
 
+## 机器门（scripts/ 是执法层）
+
+规范文本里的「不可议」必须由非零退出的脚本兜住，AI 的本机口头自证不可替代 CI。四门一体入口 `npm run ci`：
+
+| 门 | 命令 | 要点 |
+|----|------|------|
+| 版本同源 | `npm run check:version` | `package.json` == `.claude-plugin` == `.codex-plugin` == release tag 去 `v` |
+| 能力一致性 | `npm run check:requires:strict` | CI 必须 strict：解析不到 CLI 命令目录即判红，禁止「未参与断言」半绿 |
+| 知识治理 | `npm run check:knowledge` | 卡片字段/status/source（含归档兜底）/menu 路由/死链/废弃残留/孤儿规范/技能 frontmatter |
+| 产物与安装器 | `npm test` | pack 内容契约与离线安装器断言，矩阵覆盖 windows |
+
+CI 两条流水：`quality-gate.yml`（push main + 全部 PR）、`publish-release.yml`（`release.published` → 版本权威判定 → 四门 → pack → 资产名契约断言 → 上传 → 隔离 prefix 发布冒烟）。**版本权威＝release tag**，不做 CI 事后回写修正。
+
 ## Deterministic CLI
 
 brief JSON frontmatter 是变更状态唯一真相。brief、INDEX、Git 与 GitHub 写操作统一通过 `shadow-dev`，写操作必须确认并校验 planHash。禁止原始 Git/GitHub 写命令、全量暂存、`--no-verify` 和自动冲突解决。

diff --git a/README.md b/README.md
@@ -21,7 +21,8 @@ norms/                      # 跨项目硬规则与工程规范
 ├── api-design.md
 ├── interaction.md
 ├── code-style.md
-└── tdd-verification.md
+├── domain-model.md
+└── verification.md
 
 knowledge/                  # 跨项目经验与协作知识
 menu.md                     # 任务到规范和 Knowledge 的路由
@@ -60,9 +61,9 @@ shadow-docs/
 propose → apply → review → release → archive
 ```
 
-- **propose：** 按 menu 读取和引用 active Knowledge，记录预期知识影响。
-- **apply：** 按引用约束执行；冲突时暂停并查明原因。
-- **review：** 验证实现、约束和卡片检查方法，给出最终知识动作。
+- **propose：** 按 menu 读取和引用 active Knowledge，做领域对齐（限界上下文 / 不变量），记录预期知识影响。
+- **apply：** 按引用约束执行，以 brief 的不变量为验收对象逐条留观察点；冲突时暂停并查明原因。
+- **review：** 验证实现、约束、模型一致性和卡片检查方法，给出最终知识动作。
 - **release：** 新增、原位更新、废弃卡片或记录无需变更，然后提交发布 PR。
 - **archive：** PR merged 后将 brief 移到 archive/ 并重建 INDEX；也可由 GitHub Actions 在 issue close 时自动触发。
 
@@ -142,7 +143,31 @@ shadow-dev bind plan --host auto && shadow-dev bind execute --host <名> --plan-
 
 产物与 adapters 契约：
 
-- release 产物 `shadow-dev-workflow-v<ver>.tar.gz` 由 `scripts/pack.mjs` 打包，解包为 `shadow-dev-workflow/`，只含运行必需集（marketplace.json / package.json / README / menu.md / skills / hooks / rules / knowledge / norms / docs / scripts）。
+## 发版（Release 控制版本号）
+
+版本权威是 **GitHub Release tag**：tag 名去 `v` 必须与 `package.json.version` 及 `.claude-plugin`、`.codex-plugin` 三处同源，不一致时 `publish-release` 工作流直接判红。
+
+```bash
+node scripts/bump-version.mjs 6.7.0    # 一次同步三处 manifest（也可 --check 只判定）
+npm run ci                             # 版本 + requires:strict + 知识治理 + 测试，四门一体
+git tag v6.7.0 && git push origin v6.7.0
+gh release create v6.7.0 --generate-notes   # 之后由 publish-release.yml 接手
+```
+
+`publish-release.yml`（`on: release.published`）依次执行：版本权威判定 → 装 pin CLI → 四门 → `scripts/pack.mjs` → **资产名契约断言**（CLI 只认 `^shadow-dev-workflow-v[0-9][0-9.]*\.tar\.gz$`，名字写错等于没发布）→ `gh release upload --clobber` → **发布冒烟**：隔离 prefix 里用真实 CLI 跑 `workflow plan --release → workflow execute → bind plan`，核对物化的 8 个 skills 与规范文件。产物永远不被手工搬运，人只负责 bump 与打 tag。
+
+## 机器门（GitHub Actions）
+
+| 门 | 命令 | 判什么 | CI |
+|----|------|--------|-----|
+| 版本同源 | `npm run check:version` | `package.json` 与两份宿主清单版本一致 | quality-gate + publish-release |
+| 能力一致性 | `npm run check:requires` / `:strict` | `skills 引用 ⊆ requiresCommands ⊆ CLI 命令目录` | CI 用 **strict**：解析不到命令目录即判红，禁止「未参与断言」的半绿 |
+| 知识治理 | `npm run check:knowledge` | 卡片字段与 status、source 存在性（含归档兜底）、active 卡 menu 路由、引用死链、废弃 token 残留（`--forbid`）、孤儿规范、技能 `name/description` 一致性 | quality-gate |
+| 产物与安装器 | `npm test` | pack 产物内容契约、三清单版本机检、hook wrapper 装配、离线安装 | quality-gate（ubuntu/macos/windows × node 20/22） |
+
+`quality-gate.yml` 在 push main 与每个 PR 上跑全部四门。它存在的原因很实在：这三类门此前只能靠执行者本机口头自证，而半绿的门比没有门更危险。
+
+- release 产物 `shadow-dev-workflow-v<ver>.tar.gz` 由 `scripts/pack.mjs` 打包（发版链见上文「发版」），解包为 `shadow-dev-workflow/`，只含运行必需集（marketplace.json / package.json / README / menu.md / skills / hooks / rules / knowledge / norms / docs / scripts）。
 - `adapters/<host>.json`（schema `shadow-dev-adapter/v1`）声明宿主的 skills 发现目录、复制策略、托管标记与 hook 支持位；**新增宿主 = 新增描述符，CLI 零改动**。
 
 ## 依赖

diff --git a/knowledge/bug-investigation.md b/knowledge/bug-investigation.md
@@ -31,4 +31,5 @@ verified: 2026-08-08
 
 ## 关联知识
 
-- [TDD 与验证](../norms/tdd-verification.md)
+- [验证策略与复杂度评级](../norms/verification.md)
+- [领域模型是工作流的规格载体](domain-driven-shadow-dev.md)