create-yss-spec 2.1.7 → 2.1.9

package/template/.trae/skills/yss-hook/SKILL.md

@@ -1,47 +1,54 @@
 ---
 name: "yss-hook"
-description: Use when YSS 业务逻辑 Hook 开发规范与最佳实践。涉及 useRequest、分页查询、参数管理、数据转换、树数据加载等逻辑抽象时必须使用。
+description: Use when YSS Vue 页面涉及 vue-hooks-plus/useRequest、分页、请求缓存、轮询、URL query、异步 loading、数据转换或树数据加载。
 ---
 
 # YSS Hook 开发标准
 
-Use this skill when you need to extract page logic into `views/**/hooks/useXxx.ts` or when a page has repeated request, pagination, tree loading, or parameter handling.
+本技能用于将 `views/**` 的请求、状态与数据映射收敛到 `hooks/useXxx.ts`。页面组件只保留布局、事件绑定和渲染。
 
-## Authoritative Docs And Boundary
+## 0. 权威资料与边界
 
 - YSS UI Hooks documentation: `http://192.168.164.27:3200/hooks`
+- Vue Hooks Plus `useRequest`: `https://inhiblabcore.github.io/vue-hooks-plus/zh/hooks/useRequest/quick-start`
 - Local reference index: `references/frontend-docs.md`
 
-This skill owns page business logic hooks: request execution, pagination, parameter merging, selection state, and response mapping. Use `api-integration` when the task needs Orval API import/mutator details. Use `yss-components` for layout and component rendering. Use `yss-use-table-height` or `yss-use-tree-height` for height calculations.
+本技能负责请求执行、分页/筛选参数、选择状态、响应映射和页面级调度。接口导入与 Orval mutator 使用 `api-integration`；布局、组件与交互呈现使用 `yss-components`；高度计算分别使用 `yss-use-table-height` 或 `yss-use-tree-height`。
 
-中文说明：这个技能只管页面业务逻辑 Hook。组件怎么摆交给 `yss-components`，接口怎么导入和调用交给 `api-integration`，高度计算交给高度专项技能。
+官方 `@yss-ui/hooks` 当前公开 `useFullscreen`、`useTreeHeight`、`useTableHeight`、`useLoading`、`usePollingTask` 与 `useUrlState`。`useRequest`、防抖、缓存或重试不属于这套公开 YSS Hooks 契约。仅当项目已批准 `vue-hooks-plus` 及其具体版本时，才可使用第 3 节的 `useRequest`；不得把它命名或包装成 YSS 官方 API。
 
-## Core rule
+## 0.1 Hook 选型速查
 
-- Keep data fetching, parameter merging, and result mapping inside hooks.
-- Keep page components focused on layout, event wiring, and rendering.
-- Use one hook per business domain, not one hook per tiny helper.
+| 场景 | 首选 Hook / 模式 | 关键边界 |
+| --- | --- | --- |
+| 单次列表、详情、导出、提交请求 | 当前项目已批准的请求库；若为 Vue Hooks Plus，使用 `useRequest` | 业务 Hook 维护 loading、参数、映射和异常；不要以 `usePollingTask` 代替请求状态管理。 |
+| 搜索防抖、缓存/SWR、失败重试或请求轮询 | 已批准的 `vue-hooks-plus/useRequest` | 仅用已锁定版本的 API；同一数据源只能有一个轮询调度器。 |
+| 单个异步动作的 loading / 回调 | `useLoading` | 使用 `withLoading()` 包装动作；默认捕获错误并返回 `undefined`，需要上抛才设 `rethrowError: true`。 |
+| 后台静默刷新、多接口轮询 | `usePollingTask` | 调度和页面 loading 解耦；在写入结果前检查 `isCurrent()`，请求库支持时传入 `signal`。 |
+| 地址栏筛选、分页或详情定位 | `useUrlState` | query 是扁平字符串视图；默认 `history + replace` 不触发路由重建，依赖路由守卫时显式用 `strategy: 'router'`。 |
+| 全屏预览、编辑器、图表 | `useFullscreen` | 真实全屏必须由用户手势触发；页面全屏仅是 CSS 覆盖层，不调用浏览器 Fullscreen API。 |
+| 树或表格自适应高度 | `useTreeHeight` / `useTableHeight` | 按各自专项技能实现；高度 Hook 不负责请求或业务状态。 |
 
-## Recommended hook shape
+## 1. 基本分层
+
+- 将请求执行、参数合并、响应映射与数据竞争处理放在 `hooks/useXxx.ts`；页面只保留布局、事件绑定和渲染。
+- 以业务域划分 Hook，而不是为每个微小工具函数各建一个 Hook。
+- 每个对外动作都必须有明确的 loading、成功、失败和数据陈旧策略；不要把这些分支留给模板或页面组件。
+
+## 2. 列表 / 分页 Hook
+
+下面示例仅说明**已批准**的 `useRequest` 具有 `manual`、`run`、`onSuccess`、`onError` 时的组织方式；`vue-hooks-plus` 的专属契约见第 3 节，其他请求库以实际 API 为准。
 
 ```ts
 export function useReportTable() {
-  const loading = ref(false);
   const tableData = ref<any[]>([]);
-  const currentParams = ref({
-    page: 1,
-    pageSize: 20,
-  });
-
+  const currentParams = ref({ page: 1, pageSize: 20 });
   const pagination = reactive({
-    current: 1,
-    pageSize: 20,
-    total: 0,
-    showSizeChanger: true,
-    showQuickJumper: true,
+    current: 1, pageSize: 20, total: 0,
+    showSizeChanger: true, showQuickJumper: true,
   });
 
-  const { run: fetchList } = useRequest(apiFn, {
+  const { loading, run: fetchList } = useRequest(apiFn, {
     manual: true,
     onSuccess: (res) => {
       tableData.value = res?.data?.list || [];
@@ -52,80 +59,142 @@ export function useReportTable() {
       pagination.total = 0;
     },
   });
-
   const query = (params: Record<string, any>) => {
     currentParams.value = { ...currentParams.value, ...params };
     return fetchList(currentParams.value);
   };
-
   const handlePageChange = (current: number, pageSize: number) => {
     pagination.current = current;
     pagination.pageSize = pageSize;
     return query({ page: current, pageSize });
   };
-
-  return {
-    loading,
-    tableData,
-    currentParams,
-    pagination,
-    query,
-    handlePageChange,
-  };
+  return { loading, tableData, currentParams, pagination, query, handlePageChange };
 }
 ```
 
-## Request rules
+- 仅当项目已批准的请求库支持时使用 `useRequest`；通常使用 `manual: true`，除非需求明确要求挂载即请求。
+- `currentParams` 是唯一参数源。筛选变化重置 `page: 1`；翻页只改 `page/pageSize`；刷新、导出和编辑后重载复用它。
+- 在 Hook 内处理成功、失败、空数据和响应映射；旧列表会误导时才在失败时清空。
+- 树数据同样由 Hook 暴露 `treeData`、`treeLoading`、`selectedKey`、`handleSelect`，并在其中处理会触发加载的选中副作用。
 
-- Prefer `useRequest` for all page requests.
-- Use `manual: true` unless the request must fire on mount.
-- Handle success and failure in the hook, not in the page component.
-- Reset list state on failure when stale data would be misleading.
+## 3. `vue-hooks-plus/useRequest`（项目已批准时）
 
-## Parameter rules
+`useRequest` 接收返回 `Promise<TData>` 的 service，并以插件组合管理 `loading`、`data`、`error`、`params`。自动模式默认在组件初始化时执行；`manual: true` 时用 `run` 或 `runAsync` 发起请求。
 
-- Keep `currentParams` as the single source of truth.
-- Reset `page` to `1` when filters change.
-- Update only `page/pageSize` on pagination actions.
-- Reuse `currentParams` for refresh, export, and submit after edit.
+```ts
+import { useRequest } from 'vue-hooks-plus';
+
+const { data, error, loading, params, run, runAsync, refresh, mutate, cancel } = useRequest(
+  searchReports,
+  {
+    manual: true,
+    debounceWait: 300,
+    onSuccess: (result, requestParams) => {
+      tableData.value = result.list;
+      pagination.total = result.total;
+    },
+    onError: (cause) => { requestError.value = cause; },
+  },
+);
+```
 
-## Tree data rules
+- `run` 会捕获异常并交给 `onError`；`runAsync` 返回 `Promise`，调用处必须自行 `catch`。`refresh` / `refreshAsync` 使用上一次 `params` 重发请求；不要在页面重拼参数。
+- `mutate(nextData | updater)` 用于乐观更新；启用 `rollbackOnError` 时，远端失败会恢复更新前数据。先保存局部错误 / 刷新策略，不能只依赖乐观 UI。
+- `cancel()` 会忽略当前 Promise 的结果和错误，并会取消仍在等待执行的防抖调用；它**不会**终止底层 Promise。若 transport 支持真正中止，service 才能额外使用其已验证的 `AbortSignal` 支持。
+- 搜索场景优先 `debounceWait`（毫秒），并按需要配置 `debounceLeading`、`debounceTrailing`、`debounceMaxWait`。组件卸载与后一次请求的竞态响应会被库忽略；需要提前停止时调用 `cancel()`。不要再叠加自定义 timer / 序号，除非已验证当前版本或 transport 存在库无法覆盖的缺口。
+- `useRequest` 的并发语义在文档版本间出现差异：页面说明从 v2.4.0 起手动调用可独立执行，而 Options 表仍列出 `concurrent`（默认 `false`）控制新旧请求关系。启用并发前，必须以项目锁定版本的类型、测试与行为为准；搜索和同一资源写入默认采用单一最新请求策略。
 
-Use the same pattern for tree data:
+### 3.1 缓存、刷新与重试
 
-- keep the request and tree mapping in the hook
-- expose `treeData`, `treeLoading`, `selectedKey`, and `handleSelect`
-- keep selection side effects in the hook when they affect data loading
+- `cacheKey` 成功后会全局共享 data 和 params：同 key 的并发实例共用 Promise、数据同步。因此 key 必须包含稳定的业务身份与影响结果的参数；不同租户、用户、筛选条件或权限视图不能共用 key。副作用、实时性强或权限敏感结果默认不启用共享缓存。
+- `staleTime` 内数据视为新鲜，不重新请求；`cacheTime` 到期清除缓存。没有 `staleTime` 时，重新挂载会先展示缓存、再后台请求（SWR）。编辑 / 提交成功后的显式 `refresh` 优先于等待 SWR。
+- `refreshOnWindowFocus: true` 在 `visibilitychange` / `focus` 后刷新，使用 `focusTimespan`（默认 5000ms）限频。只给允许后台重取的读模型开启；编辑中的表单、一次性动作和高成本查询默认关闭。
+- `retryCount` 控制失败后的重试次数，`-1` 为无限重试；未设 `retryInterval` 时按 2s、4s…且最高 30s 的指数退避。仅对暂时性网络 / 可恢复服务错误设置有限重试；认证授权、参数校验、业务拒绝、显式取消和非幂等写操作禁止自动重试。`cancel()` 可停止正在等待的重试。
+- `loadingDelay` 可延迟 loading 变为 `true`，避免短请求闪烁；它不延迟请求，也不能作为防抖替代。
 
-## Return contract
+### 3.2 请求轮询与依赖刷新
 
-Expose only what the page needs:
+- `pollingInterval > 0` 启用请求轮询；每次请求完成后等待间隔再发下一次。`manual: true` 时，先 `run/runAsync` 才启动。`pollingWhenHidden` 默认 `true`；仅在业务允许后台继续请求时保留，需暂停则显式设为 `false`。`pollingErrorRetryCount` 默认 `-1`，必须为生产读模型配置有限值或明确停止条件。
+- 同一数据源只能选择 `useRequest` 轮询或 YSS `usePollingTask` 之一，禁止嵌套或同时运行。手动刷新前 `cancel()` 当前请求 / 轮询，执行带 loading 的 `refresh`，再依据明确业务规则恢复轮询。
+- `refreshDeps` 仅在非 manual 自动模式生效；传入 `WatchSource[]` 精确声明依赖，或在理解捕获范围后用 `true` 自动收集。筛选列表通常使用显式 `query` 并在筛选变化时重置页码，不以 `refreshDeps` 隐式驱动复杂参数。
 
-- loading flags
-- list or tree data
-- current params
-- pagination or selection state
-- request and action methods
+## 4. 单一异步动作：`useLoading`
+
+`useLoading(initialValue?)` 返回 `loading`、`setLoading`、`toggleLoading` 与 `withLoading`。用 `withLoading` 包装提交、删除、导出等动作，并把刷新或状态修正写在回调中。
+
+```ts
+const { loading: removeLoading, withLoading } = useLoading();
+
+async function remove(id: string) {
+  // `withLoading` 不等同于去重锁；快速重复点击须显式短路。
+  if (removeLoading.value) return;
+  await withLoading(() => deleteReport(id), {
+    onSuccess: async () => { await query(currentParams.value); },
+    onError: (error) => { actionError.value = error; },
+  });
+}
+```
+
+- 确认弹窗属于页面 / 组件交互层；Hook 接收“已确认”的业务意图并负责执行、loading、结果更新和最小动作面。
+- `withLoading` 默认捕获异常并返回 `undefined`；调用方确实需要捕获时才设置 `rethrowError: true`。可用 `onSuccess`、`onError`、`onFinally` 或 `keepLoadingOnError` 定义行为。
+- 不要让一个全局 `loading` 掩盖多个互不相关动作；为删除、保存、导出等分别暴露必要状态。
+
+## 5. 搜索竞态、取消与并行详情
+
+`@yss-ui/hooks` 没有通用防抖、取消、缓存或重试 Hook。项目已批准 Vue Hooks Plus 时，优先遵循第 3 节；否则先确认项目请求库是否已提供这些能力，再在业务 Hook 中以最小实现处理：
+
+- 搜索建议：维护 timer、递增请求序号和（仅当客户端支持时）`AbortController`；新输入先清除旧 timer、递增序号并取消旧请求；响应写入前比较序号；在 `onScopeDispose` 清理 timer 并中止请求。不要把这些逻辑放在页面组件。
+- 并行详情：每个独立区域返回自己的 `{ data, loading, error, refresh }`，`refreshAll` 可以用 `Promise.allSettled` 聚合；某一区域失败不得清空或阻塞其他区域，也必须可单独刷新。
+- 提交类动作应回滚局部乐观状态；查询类动作只在旧数据会误导时清空。
+
+```ts
+function createDetailPanel<T>(load: () => Promise<T>) {
+  const data = ref<T>();
+  const error = ref<unknown>();
+  const { loading, withLoading } = useLoading();
+  const refresh = () => withLoading(load, {
+    onSuccess: (result) => { data.value = result; error.value = undefined; },
+    onError: (cause) => { error.value = cause; },
+  });
+  return { data, error, loading, refresh };
+}
+
+const refreshAll = () => Promise.allSettled([
+  profile.refresh(), permissions.refresh(), audit.refresh(),
+]);
+```
+
+## 6. 轮询：`usePollingTask`
+
+`usePollingTask` 是通用调度器，不管理业务数据、loading 或错误状态，也不能替代请求 Hook。它在本轮任务结束后用 `setTimeout` 安排下一轮，避免 `setInterval` 造成重叠堆积。若同一数据源已采用第 3.2 节的 `useRequest` 请求轮询，不得再使用本 Hook。
+
+```ts
+const polling = usePollingTask(async ({ isCurrent, signal }) => {
+  const result = await fetchStatus({ signal }); // 仅在客户端支持 signal 时传入
+  if (!isCurrent()) return;
+  status.value = result;
+}, { interval: 5_000, autoStart: true, pauseWhenHidden: true });
+```
 
-## Implementation order
+- `start`、`stop`、`restart` 会推进 generation；异步结果写入前必须调用 `isCurrent()`。`signal` 只有请求库真正支持时才能中止网络请求。
+- `stop()` 停止但保留 interval；`setInterval(0)` 停止并把当前 interval 置零。`runNow()` 可立即执行，`restart({ immediate: false })` 可避免手动刷新后紧接着重复请求。
+- 手动搜索 / 刷新时：先 `stop()`，走带 loading 的手动请求，再按需要 `restart()`；不可让轮询与手动请求同时竞争同一状态。
+- 默认页面隐藏时暂停后续调度；正在执行的任务不会自动取消。`continueOnError`、`resumeMode` 和 `concurrent` 必须按接口语义显式选择。
 
-1. Define the state domains: list, pagination, filters, tree, detail.
-2. Write the request entry with `useRequest`.
-3. Normalize parameters with one merged params object.
-4. Map API responses into page-ready state.
-5. Expose a minimal action surface to the page.
+## 7. URL、全屏与高度类 Hooks
 
-## Checklist
+- `useUrlState()`：返回扁平字符串 `state`、`setState`、`clearKeys`、`clearState`。`setState` 合并状态，`undefined`、`null`、空字符串删除键。默认 `mode: 'replace'`、`strategy: 'history'`；需要路由守卫或导航语义时用 `strategy: 'router'`。
+- `useFullscreen(target, options?)`：返回 `isFullscreen`、`enterFullscreen`、`exitFullscreen`、`toggleFullscreen`、`isEnabled`。浏览器真全屏需要用户手势；`pageFullscreen` 是 CSS 模拟全屏，可配置 `className`、`zIndex`，并可用 `escTip` 控制提示。
+- `useTreeHeight` 与 `useTableHeight` 通过 `ResizeObserver` 计算可用高度。树的 `extraOffset` 仅用于 YTree 内置 `filterable` 搜索区；表格可配置 `boundaryRef` 避免尺寸反馈循环，并可扣除分页、工具栏或新增按钮高度。具体布局约束交由 `yss-use-tree-height` / `yss-use-table-height`。
 
-- no duplicated request flow in the page component
-- no split source of truth for params
-- success, failure, and empty-data cases are handled
-- data mapping happens in the hook, not the template
-- pagination and tree loading are decoupled when they represent different domains
+## 8. 返回契约与自检
 
-## Do not
+对页面只暴露必要的 loading、数据、错误、当前参数、分页 / 选择状态和动作方法。实现前依次定义状态域、单一参数源、请求入口、响应映射和页面动作面。
 
-- do not copy the same request logic into multiple pages
-- do not keep pagination state in both the hook and the component
-- do not let the page component perform nontrivial response mapping
-- do not mix unrelated domains into one hook unless they are inseparable
+- 页面没有重复请求、响应映射或防抖竞态逻辑。
+- 参数没有双数据源；筛选、分页、刷新和导出遵循同一份参数。
+- 成功、失败、空数据、陈旧响应和重复点击均有行为定义。
+- 并行区域可独立展示失败和刷新；轮询不会覆盖更新后的手动结果。
+- 使用 Vue Hooks Plus 时，已确认包版本；缓存 key 已隔离身份和筛选；重试、焦点刷新和隐藏页轮询均有明确的开启理由。
+- 不将 YSS `usePollingTask` 与 `useRequest` 轮询叠加，也不将 `cancel()` 误认为能终止底层网络请求。
+- 不复制同一请求到多个页面，不在页面和 Hook 同时维护分页，也不把无关业务域揉进一个 Hook。

package/template/.trae/skills/yss-hook/references/frontend-docs.md

@@ -1,9 +1,10 @@
 # yss-hook Frontend Documentation
 
-Generated: 2026-08-17T12:03:37.436Z
+Generated: 2026-08-18T00:00:00+08:00
 
 Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.
 
 - hooks: http://192.168.164.27:3200/hooks
+- vue-hooks-plus/useRequest: https://inhiblabcore.github.io/vue-hooks-plus/zh/hooks/useRequest/quick-start
 
-When documentation and local code differ, inspect the current project code before editing and prefer established local usage.
+When documentation and local code differ, inspect the current project code before editing and prefer established local usage. `vue-hooks-plus` is a third-party request library, not an `@yss-ui/hooks` API; confirm the package and version are approved before using its options.

package/template/.trae/skills/yss-product-lifecycle/SKILL.md

@@ -14,7 +14,7 @@ YSS 产品研发的全生命周期主控编排器。它决定阶段、条件门
 3. `template-source` 只走模板维护流程；不得生成具体产品 Spec、原型、OpenAPI 或切片 Ticket。
 4. `project-instance` 以 `docs/process/lifecycle-registry.yaml`、由其派生的 `docs/process/lifecycle-artifact-map.md` 和 `docs/process/harness-process-tailoring.md` 为阶段、门禁和裁剪事实来源。
 
-YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask-matt` 仅在用户显式调用时作为 Matt 通用导航，且不得修改 Matt skills。
+YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask-matt` 仅在用户显式调用时作为 Matt 通用导航：不得写生命周期资产或改变门禁/Ticket 状态，并须在任何写入前回交本编排器。不要修改 Matt skills 来复制 YSS 规则。
 
 ## 选择模式
 
@@ -31,7 +31,7 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 
 - 保留生命周期注册表定义的主阶段；其中条件门禁全部按影响面强制。命中项必须达到 `approved`，未命中项记录 `not-applicable` 和原因；产物、工作单元和证据不得被统称为门禁。
 - 安全 / 权限不设独立生命周期资料、专属门禁或 `not-applicable` 记录。只有需求或冻结资产明确要求改变认证、授权、租户隔离、敏感数据或合规行为时，才把该行为写入普通 Spec、API、架构、验收和测试 seam，并仅按实际 UI、API、Backend、Data、High-risk 影响触发既有门禁；普通 action 注册、沿用认证中间件、未变化的 `401` / `403`、一般字段、SQL / DDL / 迁移和上传 / 下载本身不触发安全 / 权限流程。
-- 有效 `yss-project.yaml` 存在时，`ask-matt` 和 `setup-matt-pocock-skills` 只能作为子流程；最终入口、仓库身份和模式裁决归本编排器。
+- 有效 `yss-project.yaml` 存在时，Matt user-invoked skill 保持显式用户入口。生命周期可以准备和验收其结果，但不得自动调用它们或代替其创建正式资产；最终入口、仓库身份和模式裁决归本编排器。
 - `template-source` 命中产品 flow 时必须返回 `blocked`（`template-source-product-artifact-forbidden`），不得继续到产品资产或 Ticket 生成。
 - `template-source` 迁移共享工具或验证器前，先区分维护侧构建资产、实例分发面和实例运行资产；冻结公开入口、运行时前提、旧实现处置和跨仓消费者契约后，才可改写实现。
 - 替换自身验证门禁时，不得只用候选门禁自证；必须保留独立 baseline oracle 或同一 fixture 的双跑证据。涉及共享运行资产时，只有生成/同步实例、失败回滚和跨仓消费者的 fresh evidence 齐备，才能声明生态完成或可发布。
@@ -39,10 +39,10 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - 父 Ticket/checkpoint 的状态只是索引；与真实资产冲突时，以权威资产为准并修复索引。
 - 上游变化按依赖图精准传播 `stale`；不要无条件重跑完整阶段。
 - Matt 五态保持原义。只有解除阻塞、门禁通过且可直接实现的垂直切片才能使用 `ready-for-agent`。
-- YSS active 调用 `to-spec` 时，必须把 Matt 独立 flow 的 `ready-for-agent` 发布提示归一化为 Spec `ready-for-human`；不得把 Spec 初稿当作可直接实现的 Ticket。
-- YSS active 调用 `to-tickets` 时，新建垂直切片统一写为 `ready-for-human`；只有本编排器复算完整 `ready-for-agent` 公式后才能提升，Matt 的通用默认标签不得提前覆盖生命周期状态。
-- `orchestrate`/`resume` 连续执行安全工作单元，直到人工门禁、真实阻塞、新授权、实现/发布裁决或专项失败。
-- 进入实现后继续主控，通过 `yss-router`、`implement`、`tdd` 和 YSS 专项 skills 执行；独立审查和 fresh verification 后才能作完成判断。只有工作单元真实触碰当前用户、审计、加密或明确的权限业务行为时，才增加 `yss-userinfo`、`yss-audit-log`、`yss-security-algorithm` 等专项依赖。
+- 用户显式运行 `to-spec` 后，生命周期必须把其 `ready-for-agent` 发布提示归一化为 Spec `ready-for-human`；不得把 Spec 初稿当作可直接实现的 Ticket。
+- 用户显式运行 `to-tickets` 后，新建垂直切片统一写为 `ready-for-human`；只有本编排器复算完整 `ready-for-agent` 公式后才能提升，通用默认标签不得提前覆盖生命周期状态。
+- `orchestrate`/`resume` 连续执行安全的准备、校验和 model-invoked 工作单元，直到需要显式用户入口、人工门禁、真实阻塞、新授权、实现/发布裁决或专项失败。
+- 进入实现准备后继续主控，通过 `yss-router`、`code-review` 和 YSS 专项 skills 执行允许的 model-invoked 工作单元；`implement` 本身仍须由用户显式启动，并在其自身流程内按需使用 `tdd`，结果回交后再做独立审查和 fresh verification。只有工作单元真实触碰当前用户、审计、加密或明确的权限业务行为时，才增加 `yss-userinfo`、`yss-audit-log`、`yss-security-algorithm` 等专项依赖。
 - 原型确认 → 后端脚手架：命中产品设计影响时，先按 `yss-prototype-stage` 形成交互说明、独立 Prototype Review、高保真 HTML、AntD CLI 与浏览器验证、用户确认；只有 `gate.prototype-reviewed`、`gate.prototype-verified` 和 `gate.user-confirmation` 均满足时，才能进入下游。若 backend `scaffold_status=required`，随后先完成工程基线，由 `yss-router` 编译脚手架受控生成工作单元合同，经生命周期编排器批准并持久化后，才使用 `yss-ddd-scaffold-generator` 生成后端骨架；随后由 `yss-backend-scaffold-parent` 校验并重新进入 `yss-router`，不得先写业务代码。
 - 所有后续生成的后端代码都必须消费生命周期批准、已持久化且版本当前的 Slice Implementation Contract，绑定最小 YSS skill 闭包、允许写路径、证据文件和 YSS Skill Execution Result；没有这些证据时必须阻断。
 - Harness 内承载运行时代码时，项目路径策略固定为 `apps/backend/<project>/` 和 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅是项目容器，`app/backend/`、`app/frontend/` 及其子路径禁止生成。外部实现仓库不强制使用该目录，但必须登记真实项目根路径并写入合同。
@@ -51,13 +51,14 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 - 小改动和中等变更允许同一独立执行者完成 Review 与 fresh verification；该执行者不得是实现者。新模块、高风险或职责冲突时拆分 Reviewer 与 Verifier。
 - 进入 `code-review` 前必须持久化或明确传入 `review_mode`、`review_base_ref`、`candidate_snapshot_ref`、`candidate_digest` 和完整候选引用；`worktree` 模式必须一次捕获 committed、staged、unstaged、untracked，并让两个 Reviewer 消费同一快照，不能用只看 `HEAD` 或实时变化的 diff 宣称已审查。候选 manifest 和 `yss-worktree-candidate-v1` 不可变摘要流以 `orchestration-contract.yaml.review_input` 为唯一机器契约。
 - 实现授权不包含 Git 授权。只有用户分别明确给出值为 `true` 的 `commit_authorized` / `push_authorized`、非空 scope 和对应 `*_authorization_ref` 时才执行动作；缺失时只记录 checkpoint 判断，不得把 `implement`、`orchestrate`、当前分支或负责人要求解释成隐含授权。
+- “然后 commit”“做完提交”等自然语言意向不构成上述结构化 Git 授权，不能据此预授权或事后补齐 scope / authorization ref。
 - 连续自动推进期间累积 Ticket/Git 证据，在人工暂停、handoff、进入实现、合并或发布边界集中 checkpoint；不为每个连续经过的概念阶段重复写同类记录。
 - 跨线程、仓库、原型分支或上下文边界时使用 `handoff` 或等价记录。
 - 在 Matt 阶段边界（phase boundary）先按 `Continue → /clear → /handoff → subagent → /compact` 判断上下文动作；只在 checkpoint 记录可选 `phase_boundary` 证据，不新增生命周期状态。
 - `to-questionnaire` 进入结构化 `external-input-required` 暂停；回答回流后必须重新分类影响面并更新权威资产，不能直接恢复下游实现。
-- `wait-what` 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` 状态；`wizard` 只处理人工才能完成的步骤，默认临时使用，秘密值不得进入持久化输出。
+- `wait-what` 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` 状态；Agent 无法替代的人工步骤使用显式人工 checkpoint，秘密值不得进入持久化输出。
 - Matt `prototype` 是保留在 `prototype/<name>` 分支的单文件可分享 HTML 主来源；YSS 高保真 HTML 原型仍必须经过 Prototype Review、AntD CLI、浏览器验证和用户确认，两者不得互相替代。
-- Matt skill 返回结果必须先归一化为 `Matt Skill Result`；`drift`、`new_impacts`、`violation`、`stale_candidates`、缺失证据或不完整结果不得推进为 `completed`。
+- 新工作单元返回 `Workflow Execution Result`；旧 `Matt Skill Result` 仅可兼容读取后归一化。`drift`、`new_impacts`、`violation`、`stale_candidates`、缺失证据或不完整结果不得推进为 `completed`。
 
 ### 原型完成后的后端脚手架与代码生成边界
 
@@ -91,6 +92,6 @@ YSS 仓库以本 skill 为直接入口，不机械嵌套调用 `ask-matt`。`ask
 
 ## 输出
 
-始终输出：模式、当前阶段、影响面、证据、资产/门禁状态、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断；调用 Matt skill 时追加 `Matt Skill Result`。
+始终输出：模式、当前阶段、影响面、证据、资产/门禁状态、阻塞项、本轮动作、下一工作单元、暂停或继续理由、Ticket 同步和 Git checkpoint 判断；追加 `Workflow Execution Result`，并注明 workflow reference 或实际 model-invoked skill。
 
 暂停时只提出一个具体人工决策，并给出推荐答案与确认后的恢复动作。`audit`/`route` 不得写文件、Ticket、标签或 Git。

package/template/.trae/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -5,42 +5,48 @@ Matt skills 决定如何工作；YSS 生命周期决定是否允许推进；YSS
 ## 入口与仓库身份裁决
 
 - 所有入口先读取 `yss-project.yaml`。缺失、解析失败、schema 不支持或 `repository_mode` 非法时，停止路由并进入 migration-check。
-- **直接调用 `ask-matt`** 时，它只能提供通用 Matt flow 导航；有效 YSS 仓库必须把最终阶段、影响面、门禁和状态裁决交回 `yss-product-lifecycle`。
-- **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用 `ask-matt`；编排器直接使用兼容映射。Matt skills 作为固定上游使用，不在 YSS 精简中修改。
+- **直接调用 `ask-matt`** 时，它只能提供通用 Matt flow 导航，不得写生命周期资产、改变门禁或 Ticket 状态；有效 YSS 仓库必须在任何写入前把最终阶段、影响面、门禁和状态裁决交回 `yss-product-lifecycle`。
+- **直接调用生命周期管理的 Matt user-invoked skill**（`setup-matt-pocock-skills`、`grill-with-docs`、`to-spec`、`to-tickets`、`implement`）时，用户仍是正式资产的创建者；生命周期先校验前置条件，再接受结果并重新计算阶段、门禁和状态。它们不适用 `ask-matt` 的 `navigate-only` 限制。其他 user-invoked skill 同样不得由生命周期自动调用；只有在其专属适配合同存在时才进入 YSS 流程。
+- **直接调用 `yss-product-lifecycle`** 时，不机械嵌套调用任何 Matt user-invoked skill；编排器直接使用兼容映射，并只调用允许的 model-invoked 原语。Matt user-invoked skill 保持显式入口，生命周期只准备、校验并验收其结果。
 - `template-source` 只允许进入模板维护流程。命中 `to-spec`、`to-tickets`、`implement`、Release 或 Retrospective 时返回 `blocked`，原因是 `template-source-product-artifact-forbidden`；`ask-matt` 和 `setup-matt-pocock-skills` 都不得为具体产品生成 Spec、prototype、OpenAPI 或垂直切片 Ticket。
 - `project-instance` 才允许进入产品 Discovery → Spec → 设计 → 契约 → Ticket → 实现 → Release / Retrospective 链路。
 
 | 情形 | Matt flow | 生命周期验收 |
 |---|---|---|
-| 首次启用或配置缺失 | `setup-matt-pocock-skills` | 幂等核对 tracker、真实标签和领域布局；冲突时迁移而非覆盖 |
+| 首次启用或配置缺失 | `setup-matt-pocock-skills`（用户显式） | `needs-human`，说明缺失项；用户完成 setup 后重新计算 readiness |
 | 通用入口 | `ask-matt` | 检测到 YSS 后由本编排器最终裁决 |
-| 需求澄清 | `grill-with-docs`、`domain-modeling` | 按退出判定检查未决项和回流 |
+| 需求澄清 | `grill-with-docs`（用户显式）或 `grilling`、`domain-modeling`（生命周期原语） | 按退出判定检查未决项和回流 |
 | 信息在其他人手中 | `to-questionnaire` | 使用 `external-input-required` 暂停；答案回流后记录 response、重新分类影响面，再进入 `grill-with-docs` 或 `to-spec` |
 | 大型模糊工作 | `wayfinder` | map 真正完成后 `handoff → to-spec` |
 | 技术事实 | `research` | 一手资料回填 Spec/OpenAPI/架构/ADR |
 | runnable 问题 | `prototype` | 生成单文件可分享 HTML，保留 `prototype/<name>` 分支作为主来源；必须 source/return handoff 和结论回填，不得替代阶段 4 的低保真评审、Ant Design v6 高保真 HTML、AntD CLI 证据和用户确认 |
-| Spec 综合 | `to-spec` | 初稿进入 `ready-for-human`，不得直接实现 |
-| 切片 | `to-tickets` | 仅在冻结/无影响记录后拆垂直切片；初始角色为 `ready-for-human` |
-| 实现 | `implement`、`tdd` | `yss-router` 编译 Slice Implementation Contract 草案；本编排器核验并持久化后才执行，专项 Execution Result 返回后再次核验 |
+| Spec 综合 | `to-spec`（用户显式） | 生命周期准备与验收；初稿进入 `ready-for-human`，不得直接实现 |
+| 切片 | `to-tickets`（用户显式） | 生命周期准备与验收；仅在冻结/无影响记录后拆垂直切片，初始角色为 `ready-for-human` |
+| 实现 | `implement`（用户显式） | `yss-router` 编译 Slice Implementation Contract 草案；本编排器核验并持久化后才允许用户启动 implement；其内部按自身流程使用 `tdd`，结果回交后再次核验 |
 | Bug | `diagnosing-bugs`、`tdd` | 先建立红色反馈；高风险影响升级上游门禁 |
 | 审查 | `code-review` | 唯一默认代码审查入口；审查者独立，结合 Spec、仓库治理规则和 YSS 标准 |
 | 跨上下文 | `handoff` | 保存来源、阶段、未决项、命令和下一责任人 |
 | 阶段边界 | `PHASE-BOUNDARIES.md` | 按 `Continue → /clear → /handoff → subagent → /compact` 选择上下文动作；只记录证据，不扩展生命周期状态 |
 | 解释未落地 | `wait-what` | 只重新解释当前结论，不改变阶段、门禁、Ticket 或 `ready-for-agent` |
-| 人工步骤 | `wizard` | 只处理 Agent 无法替代的点击、审批、凭据和迁移步骤；默认临时使用，秘密值必须隐藏并脱敏 |
-| 编写 Agent 文档 | `writing-for-agents`、`writing-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
+| 人工步骤 | 人工 checkpoint | 记录 Agent 无法替代的点击、审批、凭据和迁移步骤；秘密值必须隐藏并脱敏 |
+| 编写 Agent 文档 | `writing-for-agents`；维护 skill 时使用 `maintaining-skills` | 共享 skill 只改 `.agents/skills`；流程文档保持简体中文 |
 
 尽量不修改 Matt skill 以复制 YSS 规则。只有它违反模板硬门禁时才做最小兼容修改。
 
 Router 只能返回 `draft`、`blocked` 或 `ready-for-lifecycle-review`，不得自行批准合同、设置 `ready-for-agent` 或宣布完成。`new_impacts`、`drift`、`violation`、越界路径或缺失实际验证会暂停当前工作单元，并由本编排器决定增量重路由、完整重路由或回到更早生命周期阶段。
 
-## Matt Skill Result
+## Workflow Execution Result
 
-Matt skill 的自然语言执行结果必须先归一化为 `Matt Skill Result`，再由生命周期编排器验收。结果至少包含：
+生命周期工作单元必须输出 `Workflow Execution Result`，再由编排器验收。旧 `Matt Skill Result` 仅可通过只读 compatibility adapter 归一化，且不得影响路由或作为行为基线；workflow reference 不表示调用了对应 Matt user-invoked skill。结果至少包含：
 
 ```yaml
+result_schema: workflow-execution-result-v1
+work_unit: work-unit.spec-synthesis
+workflow_reference:
+  source: mattpocock/skills
+  skill: to-spec
+  invocation_mode: reference
 result: completed # completed / blocked / needs-human / failed
-skill: <skill-name>
 evidence_refs:
   - docs/process/yss-product-lifecycle-orchestrator-validation.md
 changed_artifacts: []
@@ -54,15 +60,17 @@ blocking_signals: []
 
 Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-for-lifecycle-review → needs-human`。这里的 `completed` 只表示 Matt 工作单元已产出可验收结果，不表示生命周期完成或可发布。
 
-`completed` 的 `evidence_refs` 至少包含一条可读取或可解析的证据引用；只有字段存在但为空，不能证明工作单元完成。
+`completed` 的 `evidence_refs` 至少包含一条可读取或可解析的证据引用；只有字段存在但为空，不能证明工作单元完成。正式 Spec、Ticket 或实现资产仍只能由对应显式用户入口创建。
 
 ## Matt flow 前置条件
 
 | Matt flow | 进入条件 | 生命周期结果 |
 |---|---|---|
-| `to-spec` | `grill-with-docs` 已满足退出条件，且不存在未回流的 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | Spec 初稿为 `ready-for-human`，不等于批准 |
-| `to-tickets` | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 只能生成垂直切片 Ticket；YSS active 的 `to-tickets` 初始统一为 `ready-for-human` |
-| `implement` | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 单会话实现同样适用，不得绕过门禁 |
+| `to-spec`（用户显式） | Discovery work unit 或 `grill-with-docs` 已满足退出条件，且不存在未回流 runnable blocker；用户问题、MVP/非目标、成功标准、测试 seam 和术语审查均有证据 | 生命周期只准备/验收；Spec 初稿为 `ready-for-human`，不等于批准 |
+| `to-tickets`（用户显式） | OpenAPI Freeze 或 `no-api-impact` 记录、必要门禁、垂直切片范围和阻塞边均已明确 | 生命周期只准备/验收；只能生成垂直切片 Ticket，初始统一为 `ready-for-human` |
+| `implement`（用户显式） | `ready-for-agent` 公式、Contract 已批准/持久化/版本一致、Build Architecture Checklist、实现仓库/分支/CI/验证命令/回滚点，以及后端 Contract（适用时）均满足 | 生命周期只准备/验收；单会话实现同样适用，不得绕过门禁 |
+
+`grill_exit` 不是“已经聊过”的自然语言声明。它必须同时证明 frontier 为空、事实已解决或分别路由到 `research` / prototype / external input、用户决策已确认、双方共同理解已确认，并且没有未回流的 runnable blocker。
 
 ## Review 候选与 Git 授权
 
@@ -70,9 +78,11 @@ YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mod
 
 Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
 
+“然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。
+
 ## Setup readiness
 
-编排器先做幂等 readiness 检查，再决定是否调用 `setup-matt-pocock-skills`。检查结果只能是：
+编排器先做幂等 readiness 检查。`missing` 时不得调用 `setup-matt-pocock-skills`，而是结构化暂停并请用户显式运行它。检查结果只能是：
 
 `ready`、`missing`、`conflict`、`degraded`、`not-applicable`。
 
@@ -82,6 +92,8 @@ Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明
 
 当 YSS 生命周期处于 active 状态时，Matt `to-spec` 中独立运行时的 `ready-for-agent` 发布提示由本适配层覆盖为 `ready-for-human`：Spec 必须先经过产品总体设计 / 功能架构、必要的设计与契约门禁，之后才由生命周期编排器决定垂直切片 Ticket 的 `ready-for-agent`。这只约束 YSS 编排下的状态写入，不修改 Matt skill 单独运行时的核心行为。
 
+`setup-matt-pocock-skills` 仅由用户显式启动。readiness=`missing` 时返回 `needs-human`、`requested_skill=setup-matt-pocock-skills` 和 `resume_route=setup-readiness`；仅发现旧路径资产仍进入 migration-check 并暂停写入。`ready` 直接继续，`conflict` 进入迁移裁决，`degraded` 保留待发布草案，`not-applicable` 仅验证模板契约。通用 setup 文案与 YSS tracker 合同冲突时，以 `docs/agents/issue-tracker.md` 和本编排契约为准。
+
 ### Local Markdown 兼容映射
 
 当 `docs/agents/issue-tracker.md` 的 `platform` 为 `local-markdown` 时，Matt flow 的本地输出归一化为以下 YSS 载体：

package/template/.trae/skills/yss-product-lifecycle/references/orchestration-contract.yaml

@@ -35,8 +35,18 @@ entry_routing:
   invalid_manifest:
     action: migration-check
   direct_matt_entry:
+    skill: ask-matt
     delegate_to: yss-product-lifecycle
     requires_valid_manifest: true
+    action: navigate-only
+    lifecycle_state_mutation: forbidden
+    lifecycle_artifact_write: forbidden
+    return_to_orchestrator: required
+  formal_user_entry:
+    skills: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+    action: lifecycle-validate-and-accept
+    lifecycle_artifact_write: conditional-explicit-user-entry
+    return_to_orchestrator: required
   template_source:
     route: template-maintenance
     forbidden_artifacts: [product-spec, prototype, openapi, vertical-slice-tickets]
@@ -44,8 +54,11 @@ entry_routing:
     on_forbidden_flow: blocked
     block_reason: template-source-product-artifact-forbidden
 
-# Matt skill 的自然语言输出必须先归一化，再由生命周期编排器决定是否推进。
+# 旧 Matt Skill Result 只用于兼容读取；所有生命周期新输出使用 Workflow Execution Result。
 matt_skill_result:
+  status: compatibility-read-only
+  may_influence_routing: false
+  normalize_to: workflow-execution-result-v1
   schema_version: 1
   result_values: [completed, blocked, needs-human, failed]
   required: [result, skill, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
@@ -60,6 +73,59 @@ matt_skill_result:
     blocked: blocked
     ready-for-lifecycle-review: needs-human
 
+workflow_execution_result:
+  canonical_output_schema: workflow-execution-result-v1
+  accepted_input_schemas: [workflow-execution-result-v1]
+  legacy:
+    matt-skill-result-v1:
+      status: compatibility-read-only
+      may_influence_routing: false
+      normalize_to: workflow-execution-result-v1
+      removal_target: schema_version_2
+  result_values: [completed, blocked, needs-human, failed]
+  required: [result_schema, work_unit, workflow_reference, result, evidence_refs, changed_artifacts, new_impacts, stale_candidates, next_route, blocking_signals]
+  blocking_signals: [drift, new_impacts, violation, missing_evidence, stale_candidates]
+  completed_requires_empty: [new_impacts, stale_candidates]
+  completed_requires_non_empty: [evidence_refs]
+  completed_requires_readable_evidence_refs: true
+  evidence_ref_validation: readable-or-resolvable
+  completed_requires_no_blocking_signals: true
+  workflow_reference:
+    required: [source, skill, invocation_mode]
+    source: mattpocock/skills
+
+# Matt user-invoked skills remain explicit user entry points. Lifecycle work units
+# may prepare, validate and accept their results, but cannot invoke them or create
+# their formal artifacts on their behalf.
+matt_invocation_boundary:
+  user_invoked_skills: [ask-matt, batch-grill-me, grill-me, grill-with-docs, handoff, implement, improve-codebase-architecture, loop-me, setup-matt-pocock-skills, setup-ts-deep-modules, teach, to-questionnaire, to-spec, to-tickets, triage, wait-what, wayfinder, writing-beats, writing-fragments, writing-shape]
+  lifecycle_managed_user_entries: [setup-matt-pocock-skills, grill-with-docs, to-spec, to-tickets, implement]
+  model_invoked_skills: [grilling, domain-modeling, code-review]
+  lifecycle_may_invoke_user_invoked: false
+  formal_artifact_owner: explicit-user-entry
+  continuous_orchestration: prepare-and-validate-only
+  direct_user_entry: lifecycle-validate-and-accept
+
+lifecycle_workflow_references:
+  work-unit.discovery-interview:
+    invocation_mode: model-invoked
+    skills: [grilling, domain-modeling]
+  work-unit.spec-synthesis:
+    workflow_reference: to-spec
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.ticket-decomposition:
+    workflow_reference: to-tickets
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.slice-implementation:
+    workflow_reference: implement
+    invocation_mode: reference
+    formal_artifact_owner: explicit-user-entry
+  work-unit.code-review:
+    invocation_mode: model-invoked
+    skill: code-review
+
 flow_preconditions:
   to-spec:
     required: [grill_exit, no_unresolved_runnable_blocker]
@@ -73,6 +139,15 @@ flow_preconditions:
     required: [ready_for_agent, slice_contract_approved, slice_contract_persisted, slice_contract_current_version, build_architecture_checklist, implementation_repo, implementation_branch, ci, verification_commands, rollback_point, backend_slice_contract_if_applicable, backend_scaffold_policy_satisfied]
     applies_to_single_session: true
 
+grill_exit:
+  required: [frontier_empty, facts_resolved_or_routed, decisions_confirmed, shared_understanding_confirmed, no_unresolved_runnable_blocker]
+  facts_resolved_or_routed:
+    technical_fact: research
+    runnable_question: handoff-prototype-handoff
+    external_decision: external-input-required
+  user_confirmation_required: true
+  output: discovery-evidence
+
 ticket_role_transition:
   yss_active:
     to_tickets_initial_role: ready-for-human
@@ -131,6 +206,7 @@ review_input:
     completion_requires_current_digest: true
 
 git_authorization:
+  natural_language_intent_is_authorization: false
   commit:
     requires_explicit_user_authorization: true
     required: [commit_authorized, commit_scope, commit_authorization_ref]
@@ -230,6 +306,15 @@ tracker:
 setup_readiness:
   evaluation: once_per_task
   recheck_when: [tracker_changed, remote_changed, labels_changed, configuration_changed]
+  missing_action: needs-human
+  requested_skill: setup-matt-pocock-skills
+  resume_route: setup-readiness
+  preserves: [lifecycle.status, gate.status, ticket.role]
+  lifecycle_may_invoke_setup: false
+  legacy_artifacts_detected:
+    action: migration-check
+    setup: forbidden
+    write: paused
   states: [ready, missing, conflict, degraded, not-applicable]
   evidence: [platform, label_check, domain_layout, artifact_root, migration_ref]
   semantics:
@@ -366,5 +451,5 @@ prototype_modes:
 
 behavioral_invariants:
   wait_what_preserves_state: true
-  wizard_human_only: true
+  human_checkpoint_required_for_manual_steps: true
   diagnostics_redact_secrets: true