fix: stabilize hiui-page-workflow bundle install

skills/hiui-page-workflow/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.1 - 2026-07-08
+
+- raise the declared `ux-walkthrough` dependency floor to `>=1.0.2` so the workflow contract matches the new formal UX completion gates
+- prepare the workflow release metadata for the `ux-walkthrough` 1.0.2 checklist-coverage upgrade
+- switch the default public workflow bundle from fixed commit pinning to `XiaoMi/hiui:master` with `follow-source-manifest`
+- document release-lock freezing as an opt-in path for reproducible public snapshots
+
 ## 1.1.0 - 2026-07-07
 
 - align workflow planning and execution guidance with the current `hiui-design` Plan Gateway and execution-permission contract

skills/hiui-page-workflow/README.md

@@ -50,21 +50,31 @@
 - `git`
 - `node`
 - `python3`
-- 对公开 GitHub 仓库和分支的访问能力
+- 对公开 GitHub 仓库的访问能力
 
 默认安装会写入当前环境的本地 skills 目录。若需指定其他位置，可使用 `--target`，或在 shell 中设置 `WORKFLOW_HOME`。
 
-### Public Preview Install
+以下示例默认都从仓库根目录执行。
 
-当前灰度版通过公开 fork 分支安装四个 skill。若你希望验证在线安装，可直接拉取灰度分支并执行默认安装入口：
+### Public Install
+
+公开安装的默认入口是 `skills/hiui-page-workflow/install-workflow.sh`。`install.sh` 与 `install-codex.sh` 仍然保留，但只作为兼容壳转调。
+
+若你希望从上游仓库安装，可直接拉取 `XiaoMi/hiui` 并执行：
 
 ```bash
-git clone --depth 1 --branch gray-skill-bundle-20260703 https://github.com/1108guorui-web/hiui.git
+git clone https://github.com/XiaoMi/hiui.git
 cd hiui
 bash skills/hiui-page-workflow/install-workflow.sh
 ```
 
-也可以在已有仓库副本中直接运行：
+若外部成员仍使用旧入口，也应保持可用：
+
+```bash
+bash skills/hiui-page-workflow/install.sh
+```
+
+在已有仓库副本中，也可以直接运行默认入口：
 
 ```bash
 bash skills/hiui-page-workflow/install-workflow.sh
@@ -75,30 +85,30 @@ bash skills/hiui-page-workflow/install-workflow.sh
 安装或升级到 bundle 推荐版本：
 
 ```bash
-bash install-workflow.sh
+bash skills/hiui-page-workflow/install-workflow.sh
 ```
 
 只查看安装计划，不真正写入：
 
 ```bash
-bash install-workflow.sh --dry-run --json
+bash skills/hiui-page-workflow/install-workflow.sh --dry-run --json
 ```
 
 重新覆盖安装同版本：
 
 ```bash
-bash install-workflow.sh --reinstall
+bash skills/hiui-page-workflow/install-workflow.sh --reinstall
 ```
 
 强制按 lock 文件同步本地版本：
 
 ```bash
-bash install-workflow.sh --force-sync
+bash skills/hiui-page-workflow/install-workflow.sh --force-sync
 ```
 
 ### Compatibility Notes
 
-旧入口脚本仍然保留，但只作为兼容壳转调 `install-workflow.sh`。后续文档和脚本示例统一使用 `install-workflow.sh`。
+旧入口脚本仍然保留，但只作为兼容壳转调 `install-workflow.sh`。后续文档和脚本示例统一使用仓库内的 `skills/hiui-page-workflow/install-workflow.sh`。
 
 ## Project Usage
 
@@ -117,28 +127,50 @@ bash install-workflow.sh --force-sync
 - 需要强制覆盖时：显式使用 `--force-sync`
 - 需要允许降级时：显式使用 `--allow-downgrade`
 
-`workflow-bundle.lock.json` 是组合分发的真相源。当前灰度版默认使用公开 fork 的固定灰度分支加显式 `ref` 和 `path` 来定位 skill 源码，方便做一次完整的在线安装验证；完成灰度验证后，应再切回稳定上游分支、tag 或 commit。
+`workflow-bundle.lock.json` 是组合分发的真相源。默认公开 lock 现在会为四个 skill 记录统一的上游仓库、`master` 引用和 skill 路径，并通过 `versionPolicy: "follow-source-manifest"` 让安装器读取主仓库当前 manifest 版本。
+
+这意味着外部成员从 `XiaoMi/hiui` 的 `master` 执行安装时，默认拿到的是主仓库当前版本，而不是某个固定 commit 快照。它降低了维护成本，但不再承诺“同一条命令在不同时间一定得到完全相同的结果”。
+
+若需要冻结公开发布版本、做精确回滚或问题复现，应额外生成一份 release lock，把相同 bundle 改写为固定 commit SHA 引用。
 
 若你只想在临时目录验证安装，不污染本机默认落点，可先指定一个临时目录：
 
 ```bash
-WORKFLOW_HOME=/tmp/workflow-gray-test bash skills/hiui-page-workflow/install-workflow.sh
+WORKFLOW_HOME=/tmp/workflow-bundle-test bash skills/hiui-page-workflow/install-workflow.sh
 ```
 
 ## Validation And Rollback
 
 发布或变更 lock 文件前，建议按顺序执行：
 
 ```bash
-node scripts/verify-workflow-bundle.mjs --json
-node scripts/install-workflow-bundle.mjs --dry-run --target /tmp/workflow-bundle-check --json
-node scripts/release-workflow-bundle.mjs --json
+node skills/hiui-page-workflow/scripts/verify-workflow-bundle.mjs --json
+node skills/hiui-page-workflow/scripts/install-workflow-bundle.mjs --dry-run --target /tmp/workflow-bundle-check --json
+node skills/hiui-page-workflow/scripts/release-workflow-bundle.mjs --json
 ```
 
+若当前还处于仓库内开发联调、相关 skill 变更尚未进入 `XiaoMi/hiui:master`，应先使用 maintainer 专用本地 lock：
+
+```bash
+node skills/hiui-page-workflow/scripts/verify-workflow-bundle.mjs \
+  --lockfile skills/hiui-page-workflow/bundle/workflow-bundle.local.lock.json \
+  --json
+node skills/hiui-page-workflow/scripts/install-workflow-bundle.mjs \
+  --lockfile skills/hiui-page-workflow/bundle/workflow-bundle.local.lock.json \
+  --dry-run \
+  --target /tmp/workflow-bundle-check \
+  --json
+node skills/hiui-page-workflow/scripts/release-workflow-bundle.mjs \
+  --lockfile skills/hiui-page-workflow/bundle/workflow-bundle.local.lock.json \
+  --json
+```
+
+当你需要冻结一次公开发布快照时，可基于当前 public lock 额外生成 release lock，把 `ref` 从 `master` 改成固定 commit SHA，并重新执行一遍公开 lock 的三段验证。
+
 安装会自动生成备份和 `install-journal.json`。若要回滚，执行：
 
 ```bash
-node scripts/rollback-workflow-bundle.mjs --journal <journal-path> --json
+node skills/hiui-page-workflow/scripts/rollback-workflow-bundle.mjs --journal <journal-path> --json
 ```
 
 ## Repository Layout
@@ -154,4 +186,4 @@ node scripts/rollback-workflow-bundle.mjs --journal <journal-path> --json
 - 对外表述时，应始终把 `hiui-page-workflow` 说明为“团队通用 workflow”，不要把某个工具或目录写成产品默认形态
 - `install-workflow.sh` 只是默认安装入口；不要把它当成 project adapter 或其他工具适配器的替代品
 - 若下游公开 skill 尚未提供 `skill.manifest.json` 与 public contracts，应先补齐稳定面，再把它接入 bundle
-- 更新 lock 文件后，必须重新执行 `verify-workflow-bundle` 和 `release-workflow-bundle`
+- 更新 public lock 或 release lock 后，必须重新执行 `verify-workflow-bundle` 和 `release-workflow-bundle`

skills/hiui-page-workflow/SKILL.md

@@ -212,7 +212,7 @@ Gate 最小状态：
 |---|---|---|---|
 | `quick-preview` | `ux-smoke` | 轻量可用性自检 | 页面可见、主入口可见、无空白 / 错路由、最终截图留证 |
 | `standard-e2e` | `ux-standard` | 结构化 UX 验收 | evidence gate、P0 场景覆盖、P0/P1/P2 分级、P0/P1 修复闭环 |
-| `formal-e2e` | `ux-formal` | 完整 `ux-walkthrough` | 完整 SOP、report.json、docx |
+| `formal-e2e` | `ux-formal` | 完整 `ux-walkthrough` | 完整 SOP、report.json，以及当前 `ux-walkthrough` 版本要求的完成门禁（1.0.2 起含 checklist coverage 校验、标注校验与 docx） |
 
 `standard-e2e` 不要声称已完成完整 `ux-walkthrough`；它是参考 `ux-walkthrough` 标准的结构化 UX 验收。`formal-e2e` 才执行完整 `ux-walkthrough`。
 
@@ -222,7 +222,7 @@ Gate 最小状态：
 
 - `ux-smoke`：确认目标页面不是空白页、错误页、登录页或错误路由，并保留最终截图路径。
 - `ux-standard`：必须有可用证据，读取 `ux-walkthrough` 的 checklist、severity、ignore-list 和 issue examples；必须覆盖 P0 场景。
-- `ux-formal`：按 `ux-walkthrough` 的 `SKILL.md` 主流程与 `docs/onboarding/gates.md` 执行完整 SOP，包括 precheck、证据门禁、report.json 和 docx 交付。
+- `ux-formal`：按 `ux-walkthrough` 的 `SKILL.md` 主流程与 `docs/onboarding/gates.md` 执行完整 SOP，包括 precheck、证据门禁、report.json，以及当前 `ux-walkthrough` 版本要求的完成门禁（1.0.2 起含 checklist coverage 校验、标注校验与 docx 交付）。
 
 证据不足时，不输出确定性 UX 问题；只能输出“待补充证据 / 待交互验证 / 无法判断”。
 
@@ -305,7 +305,7 @@ HiUI 修改 -> 工程 gate -> 页面截图 -> UX 复查
 仅对 `hiui-design` 页面交付链路处理 usage stats：
 
 - 标准 / 严格 HiUI 页面生成完成且可渲染后，按 `hiui-design` 的 usage stats 规则收口
-- `ux-walkthrough` 的完成定义到完整报告、`report.json`、标注校验与 docx 为止；不额外要求 usage stats 或 telemetry closeout
+- `ux-walkthrough` 的完成定义到完整报告、`report.json` 与当前版本要求的完成门禁为止；1.0.2 起至少包含 checklist coverage 校验、标注校验与 docx；不额外要求 usage stats 或 telemetry closeout
 
 若 `hiui-design` 统计返回 `requires_network_authorization` 或退出码 `21`，按其规则申请一次授权。
 统计失败不阻断主任务交付，但不能静默吞掉入队或授权状态。
@@ -322,8 +322,8 @@ HiUI 修改 -> 工程 gate -> 页面截图 -> UX 复查
 - 手动回滚：`scripts/rollback-workflow-bundle.mjs`
 - 发布 smoke：`scripts/release-workflow-bundle.mjs`
 - 发布说明：`docs/bundle-release.md`
-- lock 条目默认按固定版本安装；仅当条目标记 `follow-source-manifest` 时，才允许跟随 `main`
-  等移动引用，并以源仓当前 manifest 版本作为目标版本
+- 默认公开 lock 可使用移动引用；当条目标记 `follow-source-manifest` 时，应以源仓当前 manifest 版本作为目标版本
+- 若需要对外冻结发布或做强可复现回滚，应额外生成 release lock，并把相同条目改写为固定 commit SHA 引用
 
 这些 bundle 文件只服务于组合分发、安装和回滚；页面需求细化、页面生成与 UX 验收仍按本 skill 的主 workflow 执行，不应在普通页面任务中误调用 bundle 控制脚本。
 

skills/hiui-page-workflow/bundle/compatibility-matrix.json

@@ -2,22 +2,35 @@
   "schemaVersion": 1,
   "bundleName": "hiui-page-workflow",
   "notes": [
-    "The public preview bundle resolves all skill sources from public GitHub clone URLs plus explicit ref/path entries.",
-    "Until upstream merge is complete, preview refs may point to upstream pull-request refs that carry the required skill manifests.",
+    "The public bundle resolves all four skills from the upstream XiaoMi/hiui repository with explicit git ref/path entries and follows XiaoMi/hiui:master by default.",
+    "The default lock now uses versionPolicy=follow-source-manifest, so the installed skill versions come from the current upstream manifests instead of a fixed git snapshot.",
     "Workflow 1.1.0 expects the downstream hiui-design planner contract to expose requiredDocs[].readMode, requiredActions, formalAcceptanceActions, currentExecutionState, and canStartImplementation.",
-    "The hiui-design manifest is still 1.0.0 in this branch, so compatibility must be judged by planner contract availability, not by semver label alone."
+    "The hiui-design manifest is still 1.0.0 in this branch, so compatibility must be judged by planner contract availability, not by semver label alone.",
+    "workflow-bundle.local.lock.json remains the maintainer-only path for validating unmerged workspace changes before they appear on XiaoMi/hiui:master.",
+    "When a reproducible public release snapshot is required, maintain a separate release lock that pins the same bundle to commit SHA refs."
   ],
   "testedBundles": [
     {
-      "bundleVersion": "1.1.0",
-      "channel": "canary",
+      "bundleVersion": "1.1.1-local",
+      "channel": "local-dev",
+      "skills": {
+        "hiui-page-workflow": "1.1.1",
+        "refine-product-requirements": "1.0.0",
+        "hiui-design": "1.0.0",
+        "ux-walkthrough": "1.0.2"
+      },
+      "status": "validated-local-smoke"
+    },
+    {
+      "bundleVersion": "1.1.1",
+      "channel": "master-follow",
       "skills": {
         "hiui-page-workflow": "1.1.0",
         "refine-product-requirements": "1.0.0",
         "hiui-design": "1.0.0",
         "ux-walkthrough": "1.0.1"
       },
-      "status": "validated-local"
+      "status": "validated-master-follow-smoke"
     }
   ]
 }

skills/hiui-page-workflow/bundle/workflow-bundle.local.lock.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": 1,
+  "bundleName": "hiui-page-workflow",
+  "bundleVersion": "1.1.1-local",
+  "channel": "local-dev",
+  "installPolicyRef": "install-policy.json",
+  "compatibilityMatrixRef": "compatibility-matrix.json",
+  "runtimeCompatibility": {
+    "requiredRuntimes": [
+      "node",
+      "python3"
+    ],
+    "notes": [
+      "This lock is for maintainer-only validation against the current working tree before publishing a new upstream git snapshot.",
+      "Do not use this local-source lock as the public installation default."
+    ]
+  },
+  "skills": [
+    {
+      "name": "hiui-page-workflow",
+      "installName": "hiui-page-workflow",
+      "required": true,
+      "version": "1.1.1",
+      "manifestPath": "skill.manifest.json",
+      "source": {
+        "kind": "local",
+        "path": ".."
+      }
+    },
+    {
+      "name": "refine-product-requirements",
+      "installName": "refine-product-requirements",
+      "required": true,
+      "version": "1.0.0",
+      "manifestPath": "skill.manifest.json",
+      "source": {
+        "kind": "local",
+        "path": "../../refine-product-requirements"
+      }
+    },
+    {
+      "name": "hiui-design",
+      "installName": "hiui-design",
+      "required": true,
+      "version": "1.0.0",
+      "manifestPath": "skill.manifest.json",
+      "source": {
+        "kind": "local",
+        "path": "../../hiui-design"
+      }
+    },
+    {
+      "name": "ux-walkthrough",
+      "installName": "ux-walkthrough",
+      "required": true,
+      "version": "1.0.2",
+      "manifestPath": "skill.manifest.json",
+      "source": {
+        "kind": "local",
+        "path": "../../ux-walkthrough"
+      }
+    }
+  ]
+}

skills/hiui-page-workflow/bundle/workflow-bundle.lock.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "bundleName": "hiui-page-workflow",
-  "bundleVersion": "1.1.0",
-  "channel": "canary",
+  "bundleVersion": "1.1.1",
+  "channel": "master-follow",
   "installPolicyRef": "install-policy.json",
   "compatibilityMatrixRef": "compatibility-matrix.json",
   "runtimeCompatibility": {
@@ -11,8 +11,9 @@
       "python3"
     ],
     "notes": [
-      "Local development and fixture validation can resolve source.kind=local entries relative to this lock file.",
-      "Published internal releases should replace local source entries with git-backed repo/ref/path values."
+      "Local development and fixture validation can still use dedicated local-source lock variants relative to this bundle.",
+      "The published default lock follows the upstream XiaoMi/hiui master branch and resolves each skill version from the current source manifest.",
+      "Use a dedicated release lock with commit SHA refs when you need a frozen, reproducible bundle snapshot."
     ]
   },
   "skills": [
@@ -21,11 +22,12 @@
       "installName": "hiui-page-workflow",
       "required": true,
       "version": "1.1.0",
+      "versionPolicy": "follow-source-manifest",
       "manifestPath": "skill.manifest.json",
       "source": {
         "kind": "git",
-        "repoUrl": "https://github.com/1108guorui-web/hiui.git",
-        "ref": "gray-skill-bundle-20260703",
+        "repoUrl": "https://github.com/XiaoMi/hiui.git",
+        "ref": "master",
         "path": "skills/hiui-page-workflow"
       }
     },
@@ -34,11 +36,12 @@
       "installName": "refine-product-requirements",
       "required": true,
       "version": "1.0.0",
+      "versionPolicy": "follow-source-manifest",
       "manifestPath": "skill.manifest.json",
       "source": {
         "kind": "git",
-        "repoUrl": "https://github.com/1108guorui-web/hiui.git",
-        "ref": "gray-skill-bundle-20260703",
+        "repoUrl": "https://github.com/XiaoMi/hiui.git",
+        "ref": "master",
         "path": "skills/refine-product-requirements"
       }
     },
@@ -47,11 +50,12 @@
       "installName": "hiui-design",
       "required": true,
       "version": "1.0.0",
+      "versionPolicy": "follow-source-manifest",
       "manifestPath": "skill.manifest.json",
       "source": {
         "kind": "git",
-        "repoUrl": "https://github.com/1108guorui-web/hiui.git",
-        "ref": "gray-skill-bundle-20260703",
+        "repoUrl": "https://github.com/XiaoMi/hiui.git",
+        "ref": "master",
         "path": "skills/hiui-design"
       }
     },
@@ -60,11 +64,12 @@
       "installName": "ux-walkthrough",
       "required": true,
       "version": "1.0.1",
+      "versionPolicy": "follow-source-manifest",
       "manifestPath": "skill.manifest.json",
       "source": {
         "kind": "git",
-        "repoUrl": "https://github.com/1108guorui-web/hiui.git",
-        "ref": "gray-skill-bundle-20260703",
+        "repoUrl": "https://github.com/XiaoMi/hiui.git",
+        "ref": "master",
         "path": "skills/ux-walkthrough"
       }
     }