feat: harden hiui-design planning and align workflow skill contracts

skills/hiui-design/GENERATED_DO_NOT_EDIT.md

@@ -4,6 +4,6 @@ This directory is generated from the hiui-design maintainer source by `scripts/b
 
 - target: open-source-package
 - manifestVersion: 1
-- files: 515
+- files: 495
 
 Make changes in the maintainer source, then regenerate this target.

skills/hiui-design/README.md

@@ -23,4 +23,4 @@ node <path-to-global-hiui-design>/scripts/sync-open-source-package.mjs \
 The sync is one-way. Edit the internal source skill, then regenerate this public folder.
 
 Generated by: `scripts/sync-open-source-package.mjs`
-Copied files: 516
+Copied files: 496

skills/hiui-design/SKILL.md

@@ -119,6 +119,13 @@ description: >-
   `componentSupportSources` 都能解析到真实项目源码时才成立；缺任一项时，接入必须保持
   `integrationReady=false`，页面生成阶段只允许暴露阻断原因，不得把缺失 carrier 问题延后到
   业务页实现期才发现。
+- 对 `legacy-host-compatible`，`integrationReady=true` 还要求项目级 required rollout 已完成：
+  默认先覆盖 `table-basic`、`table-stat`、`tree-table`、`tree-split`、`drawer-form`、
+  `drawer-detail`、`full-page-edit`、`full-page-detail` 这些 `carrier-first-required`
+  页型；`feedback-status` 与 `data-visualization` 可作为 deferred batch 后补。缺少 required
+  batch 的 project-certified carrier 时，integration state 必须显式输出
+  `requiredLegacyPageTypes`、`deferredLegacyPageTypes`、`certifiedLegacyPageTypes`、
+  `missingRequiredLegacyPageTypes` 与 `legacyRolloutCoverageStatus=blocked`。
 - `integrationReady` 默认只回答“项目是否已完成 hiui-design 接入”和“legacy 宿主桥接是否已具备项目级承接事实”。`rules-only` / `host-integration` 下标准典型页组件是否可用，属于 planner 消费的资产事实与页型支持事实，不应被收口为通用项目接入失败。
 - project-scoped host pack / carrier facts 也属于 runtime input facts。对 legacy 项目，应优先
   在项目接入 / capabilities 阶段一次认证，再由页面生成阶段复用，不要在每个页面重复解释宿主边界。
@@ -143,6 +150,9 @@ description: >-
   直接回显接入阻断原因；不要再尝试把页面生成、起手 scaffold 或页面级 preflight 当成接入 /
   legacy bridge 完整性的补救路径。页型级 `page-component` 资产是否 ready，继续由 planner 的
   `assetResolution` / `projectTypicalPageSupport` 独立判断，而不是反写成通用 integration debt。
+- 当 `integrationReady=false` 的原因来自 legacy required rollout 未完成时，`PlanTask` 默认应把
+  `bootstrap-target-project` 放在 `ResolveBlockingFacts` 队首；若同时命中 route ownership
+  blocker，再在其后追加 route 修复动作，不得跳过项目级 carrier rollout 直接进入页面实现。
 - `BuildGenerationRecipe`：把 `generationStrategy` 转化为标准装配协议。
 - `GenerateByRecipe`：生成行为必须遵循 `assemblyOrder`、`requiredAssets`、`forbiddenMoves`；不允许自由发明页壳、region owner、slot 顺序。
 - `InlineConformanceChecks`：关键装配步骤后的轻量一致性检查，不把重验收前移。

skills/hiui-design/distribution-manifest.json

@@ -185,7 +185,7 @@
         "scripts/README.md",
         "scripts/lib/**",
         "scripts/public-cli-contracts.json",
-        "scripts/tests/fixtures/public-cli/*.json",
+        "scripts/tests/fixtures/public-cli/preview-ready.quality-pass.json",
         "templates/**",
         "vendor/typical-page-shells-package.json",
         "vendor/hiui-design-typical-page-shells-*.tgz"
@@ -252,6 +252,8 @@
         "scripts/lib/stats-config.mjs",
         "scripts/lib/stats-identity.mjs",
         "scripts/tests/*.test.mjs",
+        "scripts/tests/fixtures/public-cli/plan-page-task*.json",
+        "scripts/tests/fixtures/public-cli/final-report*.json",
         "scripts/tests/fixtures/public-cli/*usage*.json",
         "src/typical-page-reuse/DOCTOR_REPORT.md",
         "src/typical-page-reuse/HOST_ADAPTER_SNIPPET.md",
@@ -264,7 +266,6 @@
         "distribution-manifest.json",
         "docs/onboarding/public-runtime-release-checklist.md",
         "rules/runtime-delivery-policy.json",
-        "scripts/tests/fixtures/public-cli",
         "vendor/typical-page-shells-package.json",
         "scripts/typical-page-preview-ready.mjs",
         "scripts/tests/fixtures/public-cli/preview-ready.quality-pass.json"

skills/hiui-design/docs/generation/component-certification.md

@@ -54,9 +54,14 @@
 ### Legacy runtime adapter 额外检查
 
 - `CleanContentMount` 证明旧宿主只提供干净内容挂载点，不重复提供页头、白底主体、分页 owner 或页面主滚动。
+- `CleanContentMount` 还必须证明 legacy 宿主或业务页本地 wrapper 没有重新接管 `white-body`、
+  `main-scroll` 或 `pagination` 的几何责任；若出现第二层 page surface / query shell /
+  sticky pagination shell，应视为 owner drift。
 - `RuntimeAdapter` 证明路由、权限、请求、字典、主题和用户能力通过显式 props / provider 注入，而不是页面组件读取项目全局变量。
-- `RuntimeBridge` 证明 request、auth、permission、user、dictionary、route-navigation、theme 可用且来源可追踪。
-- `StyleBoundary` 证明旧宿主全局 CSS 不会破坏页面组件的表格、分页、表单、抽屉、状态标签和间距。
+- `RuntimeAdapter` 不得重做 `QueryFilter` carrier、`pagination` carrier 或 `bodyTopNavigation`
+  carrier；这些区域只能继续由 selected page component / project-certified carrier 承接。
+- `RuntimeBridge` 证明 request、auth、permission、user、route-navigation、theme 可用且来源可追踪；`dictionary / i18n` 只在项目明确要求国际化时作为可选桥接能力补证。
+- `StyleBoundary` 证明旧宿主全局 CSS 不会破坏页面组件的表格、分页、表单、抽屉、状态标签和间距；对 legacy 表格类页型，还应覆盖搜索输入灰底、Tabs 落位、排序图标间距与分页吸底等高频几何污染风险。
 - `PortalBoundary` 证明下拉、气泡、弹窗、抽屉等浮层挂载位置和层级不会被裁切；若宿主未显式改写浮层容器，则允许沿用组件库默认挂载能力。
 - `AdapterRegistry` 证明 adapter 只做 runtime bridge，禁止 `translate-hiui-components-to-legacy-components`、`replace-query-filter-with-legacy-form`、`replace-managed-table-with-legacy-table`、`reimplement-pagination-region` 或 `wrap-typical-page-as-business-page-component`。
 

skills/hiui-design/docs/generation/implementation-checklist-template.md

@@ -162,6 +162,7 @@
 - 若需求只说“提供状态标签筛选”但未指定默认激活项，是否保持初始数据全集可见，而不是默认选中第一项造成隐式预过滤
 - 右侧详情表格区的局部 inset 是否明确落在真实内容 owner 上，而不是直接贴边
 - 页级动作是否已经进入 `PageHeader extra`
+- header slot 与 `PageHeader root` 是否共同证明了 `width: 100% + min-width: 0`，从而让 `PageHeader extra` 真正贴右，而不是仍然紧挨标题流动
 - 右侧 pane header 是否只保留上下文信息，而不是承接页面主按钮
 
 记录模板：
@@ -175,6 +176,7 @@
   - default filter state:
   - right detail/table inset owner:
   - page-level actions owner:
+  - page-header stretch owner:
   - pane header scope:
 ```
 

skills/hiui-design/docs/generation/legacy-host-compatibility.md

@@ -150,6 +150,13 @@ Don't：
 
 这里的“优先使用 standard 页面组件实现”默认解释为 `page-component + runtime bridge + slot fill`。桥接模式下，legacy 主树若不能 ad hoc direct import standard shell，只能阻止 direct shell mount；它不能单独推翻 planner 已判定 ready 的页面组件主链，也不能成为默认转去 reference/fallback 或兼容手拼页的理由。
 
+对旧系统中已经存在的业务页，bridge 快速路径还应默认优先下面两类实现动作：
+
+1. `slot-fill-only`：当前页已经是 ready 的 managed instance，且本次需求没有触碰 `pageType`、`shell`、`ownership`、mandatory components 或 runtime carrier，只替换业务槽位。
+2. `rewrite-by-page-component`：当前页仍属于同一典型页型，planner 已给出 certified page component / project carrier，但现有源码不是 ready 的 managed instance。此时应直接用 page component / carrier 重建业务页实例，而不是在旧 JSX 上继续修补 `header / query-filter / table / pagination / white-body`。
+
+`rewrite-by-page-component` 仍然属于 bridge 模式下的普通典型页主链；它不是 fallback，也不是 translated-reference。
+
 数据可视化不属于普通典型页快速路径。即使存在示例页，也必须走 `generationStrategy=managed-analytics`：先提取旧系统中的业务指标、筛选维度、接口和权限事实，再建立 `chartUsageContract`，最后由数据可视化 token 与图表组件规则生成页面实例。
 
 桥接快速路径的起点优先级：
@@ -184,6 +191,11 @@ legacy 快速路径不是全量重流程，而是按接入层 / 生成层 / 治
 2. **生成层主链路门禁**：普通典型页默认仍以 certified `pageComponent` 为主资产；只有 component 不可用、结构升级或宿主约束特殊时，才允许进入 host archetype / reference / scaffold fallback。`component-first` 只说明生成起点，不豁免 instance validation，也不把治理要求自动降到 `rules-only`。
 3. **治理层增强门禁**：只有命中转译风险、页型迁移或正式验收条件时，才显式展开 Translation Drift Guard，并按需要补齐 finalize / source gate / doctor / runtime smoke。`StyleBoundary`、`PortalBoundary`、`runtimeSmoke` 默认属于这一层的触发式检查，而不是普通表格页的必阻断项。
 
+这里要明确区分两类升级：
+
+- `implementation upgrade`：只有 `pageType`、`shell`、`ownership`、split、主工作区滚动链或 mandatory components 发生变化时，才升级成重结构改造。
+- `governance upgrade`：迁移 / 重架构页、高风险 drift、正式验收 / 发布场景，会升级 snapshot、acceptance contract、translation map、source-gate、doctor、runtime smoke 等治理动作，但不必然要求页面结构重写。
+
 若 planner 已返回 `page-component` ready、`deliveryPath=page-component-plus-slot-fill` 且 `runtimeAdapterProof.status=available`，生成阶段必须沿该主链继续；此时 direct shell import 不成立、legacy 主树不能标准壳直挂、或 reference 目录存在，都不构成擅自降级为 hand-built compatibility page 的依据。
 
 legacy 的最小 runtime adapter proof 必须能写清：

skills/hiui-design/docs/generation/non-typical-pages.md

@@ -81,6 +81,12 @@
 - free composition is allowed only inside a HiUI-first, spec-constrained frame
 - 组件优先级、视觉 token、spacing ownership、禁止大段空白、runtime shell requirements 仍然是硬门槛
 
+旧系统升级场景里，这里的“保留结构”要收窄理解：
+
+- 保留的是 `base archetype`、`layout strategy`、一级信息架构与业务语义。
+- 不保留旧视觉、旧 DOM 壳层、旧样式类名、旧 spacing owner 或未受管的布局实现。
+- 非典型升级默认是“preserve layout strategy and replace semantics”，不是“沿用旧页面实现后只换 token / 换皮肤”。
+
 ## 策略驱动生成门槛
 
 非典型页面必须先证明“为什么不能直接套典型页”，再进入 JSX / 样式实现。这里的证明不是固定某个区块组合，而是把页面的一层信息组织策略落成机器可追踪事实。
@@ -93,6 +99,8 @@
 - `composition guardrails`：说明允许自由组合的槽位、禁止替换的 carrier、禁止重写的 HiUI 骨架。
 - `strategy evidence`：说明源码和运行时需要出现哪些布局 marker / 语义组件 / 一级分组来证明策略已兑现。
 
+若旧系统升级任务已经给出稳定的 `layout strategy` 与 `layout archetype`，但没有 `pageType` / `shell` / `ownership` 级结构变化，默认升级的是语义实现与治理约束，而不是重写整页结构。
+
 阻断规则：
 
 - 用户明确要求非典型，但计划无法给出 `layout strategy` 与 `layout archetype` 时，必须 `status=blocked` 补业务意图，不能降级为自由拼装。

skills/hiui-design/docs/generation/page-level-components.md

@@ -40,10 +40,14 @@ HiUI Typical Standard -> PageType -> ManagedMold -> Adapter/Carrier Proof -> Cer
 
 `rules-only` 不是“无组件模式”。它与 `host-integration` 的主要区别是接入方式：`rules-only` 不把 host 示例页作为项目运行入口，不安装示例 gallery；但只要组件在 `supportedModes` 中声明支持 `rules-only`，并且认证 artifact 与组件的 canonical `mode` / `baseMoldId` 匹配，`plan-page-task` 就可以把它作为主生成资产。只有宿主约束要求额外 adapter 或 legacy 兼容时，才需要单独的 host-adapted / legacy-compatible component。
 
+对 `rules-only` / `host-integration` 而言，标准页面级组件是否 ready 属于 planner 的资产解析结果，不属于项目接入 readiness。接入阶段负责证明项目具备运行时 / 依赖 / 宿主前提；页面阶段再判断当前页型是否能命中 `page-component + slot-fill`。
+
 `legacy-host-compatible` 也不是“无组件模式”。它的人类解释统一为“旧宿主桥接接入模式”。这里的 `compatible` 只表示宿主边界与运行时契约可被桥接和证明，不表示任意旧宿主天然兼容，也不表示只要能挂载就已经进入受管生成 / 交付状态。它与 `rules-only` 的区别是旧宿主运行时、全局样式、portal、路由和权限接法不可直接等同于标准宿主；因此 legacy 的主路径应优先选择 **project-certified carrier implementation of page-component**。只有当宿主已经证明可直接等价承载 standard component 的运行时契约时，才直接使用 standard certified page component。旧宿主只保留全局导航、左侧菜单、路由入口和干净内容挂载点；组件内部的页头、筛选、白底主体、表格 / 表单 / 详情、分页 / 底栏和主滚动链不再拆给宿主逐项承接。这里的宿主边界证明应在项目接入 / capabilities 阶段完成，页面生成阶段只消费该证明结果；`legacy-host-family-registry.json` 中的 family `status` 是注册表生命周期标签，不是业务页生成期的硬门禁。
 
 `legacy-runtime-adapter` 是运行时转接证明，不是组件翻译器。它只能绑定 request / response / message / i18n / permission / modal / scroll / style 等运行时能力，不得把 `QueryFilter` 翻译成旧 `SearchForm`、把受管表格翻译成旧表格、重做分页区域，或把典型页整体包装成业务页面级组件。`portal-root` 默认视为浮层运行时的常规能力，不进入 runtime bridge 的硬缺口判断；只有宿主显式改写浮层容器或出现裁切风险时，才额外进入 `PortalBoundary` 事实。`host archetype` 与 `reference-or-scaffold` 是 fallback 起点；`translation-map` 是治理增强工件。只有 project-certified carrier 缺失、宿主约束特殊、direct standard component 不可直挂，或 drift 风险需要显式治理时，计划才应进入这些路径。
 
+legacy 项目默认不要求在“项目接入完成”时覆盖所有典型页型，但应先完成一批 `carrier-first-required` 的 project rollout：`table-basic`、`table-stat`、`tree-table`、`tree-split`、`drawer-form`、`drawer-detail`、`full-page-edit`、`full-page-detail`。`feedback-status` 与 `data-visualization` 可以延后，但它们不应反向稀释这批表格 / 编辑 / 详情页的 carrier-first onboarding 事实。
+
 ## Project-Scoped Carrier Overlay
 
 对 legacy 项目，推荐通过 project-scoped overlay 提供 carrier 资产，而不是把项目自己的 carrier 直接登记成 skill 全局 generic 组件名。
@@ -56,6 +60,7 @@ HiUI Typical Standard -> PageType -> ManagedMold -> Adapter/Carrier Proof -> Cer
   3. `host-archetype`
   4. `reference-or-scaffold`
   5. explicit fallback / managed translation
+- project 级 integration facts 应显式记录 `requiredLegacyPageTypes`、`deferredLegacyPageTypes`、`certifiedLegacyPageTypes`、`missingRequiredLegacyPageTypes` 与 `legacyRolloutCoverageStatus`。只要 required batch 仍缺 carrier，`plan-page-task` 就必须回到 `bootstrap-target-project` / `ResolveBlockingFacts`，而不是继续给页面实现命令。
 - project overlay 只解决项目级承载差异，不改变 `baseMoldId`、slot 边界、required regions、mandatory components 和 page-instance validation。
 
 ## Runtime-Bridged Page Components
@@ -74,6 +79,15 @@ HiUI Typical Standard -> PageType -> ManagedMold -> Adapter/Carrier Proof -> Cer
 - bridge wrapper 与 slot adapter 必须保持 thin：前者只绑定宿主 runtime / mount boundary，
   后者只做业务槽位适配；两者都不得接管 `shell`、`white-body`、`main-scroll`、
   `pagination`、`footer` 或 `route owner`。
+- 对表格类 `page-component`，`QueryFilter`、`Table` 与 `pagination` 都属于 carrier 内部语义；
+  业务页 / bridge slot adapter 只允许填 `queryFields`、表格列、行操作和 Level 1 受控扩展，
+  不允许再额外包一层外部样式容器、自由筛选栏，或把 `QueryFilter` 翻译成宿主 `SearchForm`。
+- 对 legacy 表格类 bridge，业务页、本地 wrapper 与 slot adapter 还不得再合成第二层
+  `white-body shell`、`main-scroll shell`、`pagination shell` 或 `query shell`。这些几何责任必须
+  保持在 selected certified page component 或 project-certified carrier 内部。
+- 若页面需要 `bodyTopNavigation`、筛选区前提示条或结果工具条，这些能力只能来自 page component
+  已声明的标准 slot / Level 1 受控扩展；legacy bridge 不得通过外层 wrapper 把它们提升成新的
+  page-level carrier，也不得把主体导航回流到 header region。
 - 这类 bridge 规则的唯一真相是 `rules/runtime-bridged-component-matrix.json`；它只补充
   `page-component` 在 legacy 中的交付方式，不复制 `page-component-registry`、mold registry
   或 component certification 已经表达的事实。
@@ -91,6 +105,8 @@ HiUI Typical Standard -> PageType -> ManagedMold -> Adapter/Carrier Proof -> Cer
 
 不满足时应 fail closed 或回到 `managed-fallback` / `non-typical`，不得回退到空白页手写。
 
+特别说明：legacy 主树不能 ad hoc direct import `@hiui-design/typical-page-shells`，并不等于 `page-component` 主链失效。只要 `runtimeAdapterProof` 已就绪，legacy 普通典型页的默认执行语义仍是 `page-component + runtime bridge + slot fill`；缺少 direct shell import 前提，只能阻止 direct shell mount，不能成为默认改写成兼容手拼页或把 reference 当交付资产的理由。
+
 对 legacy 普通典型页，还应默认收敛为 4 个硬门禁：
 
 1. `mode` 正确。

skills/hiui-design/docs/onboarding/distribution-governance.md

@@ -240,7 +240,6 @@ flowchart LR
 - 默认 target 是 `~/.codex/skills/hiui-design-open-source`
 - 可选携带 `--open-source-commit` / `--open-source-push`
 - 若 `sync-open-source-package.mjs --source <path>` 的 source 本身是独立 Git 维护仓根目录，脚本会先执行 `check-rules-version-alignment.mjs`；guarded 变更未 bump `rules/VERSION` 时直接 fail closed
-- `scripts/public-cli-contracts.json` 中 `machine-public` tier 声明为 `status=shipped` 且 `jsonContract=shipped` 的 fixture，属于公开分发契约的一部分；open-source package 必须稳定携带这些 `scripts/tests/fixtures/public-cli/*.json`，不能只保留文档或契约引用而丢失文件实体
 - 若本次同步涉及 `@hiui-design/typical-page-shells` 版本变化，发布前必须先执行 `node scripts/check-public-runtime-publish-readiness.mjs --source-root <global-mirror> --public-root <open-source-package-root>`，确认 vendor snapshot、vendored tgz、`packages/typical-page-shells/package.json` 和 dry-run 都一致；真实发布后再执行 `node scripts/verify-public-runtime-release.mjs --source-root <global-mirror> --public-root <open-source-package-root>`，确认 npm registry 已暴露 exact version
 - 未通过上述门禁前，不要把“开源仓已生成 `packages/typical-page-shells`”误读成“公开 npm 已可安装”
 - 具体执行顺序见 `public-runtime-release-checklist.md`