create-yss-spec 3.4.7 → 3.4.9

package/template/.agents/skills/yss-web-controller/SKILL.md

@@ -11,7 +11,7 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 
 以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
-这是一个 Web 适配层生成型 skill。优先复用脚本 `scripts/generate_controller.mjs` 和模板，不手写重复 CRUD。
+本 Skill 同时支持只读审计、既有整改和新建 CRUD 生成。审计读取实际入口和现有契约，缺证据只记录缺口；整改消费批准 Slice、冻结 API/no-impact 与稳定用例 seam；仅新建 CRUD 才要求 Web generation contract、metadata 并调用 initialize-only 生成器。
 
 ## 何时使用
 
@@ -19,12 +19,13 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 - 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
-## 不适用
+手工认证、回调、Cookie、下载或流式接口适用本 Skill，但不强制使用 CRUD 脚本或 metadata。
 
-- 用户只是要新增一个手写复杂接口，不一定要用脚本。
-- 用户还没有稳定的 Application Service、冻结 OpenAPI 或 metadata，先回 实现合同编译器 补 `yss-application` / `yss-domain` 和相应合同输入。
+## 实施前置与审计边界
 
-## 优先流程
+- 只读审计可以记录用例 seam 或契约缺失。既有整改缺少批准 Slice、稳定用例 seam 或接口契约时，回实现合同编译器补齐；仅新建 CRUD 生成要求 metadata，不因缺 metadata 拒绝既有代码审计或手工接口整改。
+
+## 新建 CRUD 生成流程
 
 1. 先确认冻结 OpenAPI、批准且版本当前的 Web generation contract schema v2、Application Service 接口、metadata、基础包、模块名、领域 segment 和 web 落盘目录；合同必须绑定 Slice `contract_id` / `contract_version` / `slice_id`、`yss-dto` wire profile 引用与 digest、允许写路径、证据与验证命令。
 2. 加载并遵守 `yss-dto` 与 `yss-validation`；错误映射影响命中时再加载 `yss-exception`。
@@ -61,13 +62,19 @@ node scripts/generate_controller.mjs \
 
 ## 约束
 
+<a id="web.use-case"></a>
+<!-- yss-rule {"id":"web.use-case","when":"web","level":"mandatory","evidence":"code-and-verification"} -->
 - 生成代码只依赖既有 Application Service；读写操作都禁止绕过 Application。复杂查询经 Application Query Port 接入 Infrastructure。
+<a id="web.wire"></a>
+<!-- yss-rule {"id":"web.wire","when":"wire","level":"mandatory","evidence":"code-and-verification"} -->
 - 返回包装类、分页默认值、允许字段与 `PageResult.of(...)` 参数语义必须消费合同绑定的 `yss-dto/references/openapi-wire-profile.yaml`；Web skill 不复制或自行维护第二套协议。
 - DTO / VO / CMD / Query 默认用 Lombok 处理 getter/setter、constructor、builder 和日志样板；不要在 Controller 内部类或非约定包临时定义主要 DTO / VO。
 - `WebConvertor` 使用 `@Mapper(componentModel = "spring")` 和构造器注入；禁止静态 `INSTANCE`、在 Controller / Application 中大段手写字段赋值、使用 `BeanUtils.copyProperties` 或反射式通用拷贝。
+<a id="web.pagination"></a>
+<!-- yss-rule {"id":"web.pagination","when":"pagination","level":"mandatory","evidence":"code-and-verification"} -->
 - HTTP Request 不继承会暴露内部协作字段的 `PageQuery`；只生成冻结 OpenAPI allowlist 字段，禁止把 `offset`、`needTotalCount`、`tempTotalCount` 变成客户端输入。
 - `fields.<table>.pagination` 必须显式列出 `yss-dto` wire profile 允许暴露的字段子集；模板不得无条件生成字段或自行定义默认值。
-- 先跑脚本，再按项目规范做少量手调。
+- 仅新建 CRUD 先跑脚本；既有整改和手工协议适配不重跑初始化生成器。
 - Validation namespace 参数必须来自批准的精确平台配置和当前工程基线，不得按记忆或 Boot 大版本自行选择。
 - 若用户只是要改单个 Controller，先看现有代码，不要盲覆盖整个目录。
 - 脚本是 initialize-only；写入前先规划全部目标并校验 `allowed_write_paths`，任一目标已存在或传入 `--force` 时整体返回 `unsupported`。落盘使用排他创建和失败回滚，不得留下部分文件；旧项目迁移不属于该生成器。
@@ -85,8 +92,10 @@ node scripts/generate_controller.mjs \
 
 ## 阶段 7 合同
 
-- 只消费已批准且当前的 schema v2 Web generation contract 和冻结 OpenAPI/no-impact record；schema v1 为 `unsupported`，不得自动升级，也不得用 Controller 或半成品 backend 反向定义产品契约。
+- 所有写入消费批准且当前的 Slice 与冻结 OpenAPI/no-impact record；只有新建 CRUD 生成还要求 schema v2 Web generation contract。生成合同 v1 为 `unsupported`，不得自动升级；不得用 Controller 反向定义产品契约。
 - DTO/VO/WebConvertor 机械骨架可用 `controlled-generation`；权限、错误映射、校验语义和接口行为必须使用 `behavior-tdd`。
+<a id="web.write-scope"></a>
+<!-- yss-rule {"id":"web.write-scope","when":"change","level":"mandatory","evidence":"code-and-verification"} -->
 - 写入必须位于合同 `allowed_write_paths`，并提供 Controller、DTO/VO、WebConvertor、契约/API 测试和实际验证结果。
 - 按统一 `YSS Skill Execution Result` 返回偏离与新增影响；出现新 API/schema、权限或响应包装变化时暂停并回到 实现合同编译器/生命周期。
 

package/template/.agents/skills/yss-web-controller/references/web-adapter-layer-guide.md

@@ -84,3 +84,11 @@ public interface QualityRuleWebConvertor {
 - Wire forbidden fields 无法绑定。
 - OpenAPI 3 注解、YSS Result wrapper、Validation namespace 与平台 Profile 一致。
 - 执行项目根 `./mvnw test/package`，并保留 HTTP/serialization/exception 证据。
+
+## 非 CRUD 适配
+
+认证、OAuth 回调、Cookie、流式响应及协议端点可以手工实现，不强行套 CRUD metadata；仍消费批准的 wire 合同、Application seam 和平台配置。Controller 不直连 Domain Gateway，也不自行编排登录、撤销或持久化。
+
+协议转换、Cookie/Header 处理归 Web；业务决策归 Application/Domain。异常翻译器可以依赖领域错误类型，不能据此允许 Controller 调用领域端口。MapStruct 处理机械字段映射，协议编码及显式领域工厂适配使用有测试的自定义方法。
+
+生成器推荐 rest 布局；已登记的 adapter.web 等布局通过合同绑定识别。审查按模块、实际 Controller 类型和依赖方向进行，包名偏离不能让检查空匹配通过。

package/template/.agents/skills/ytable-usage/SKILL.md

@@ -216,7 +216,7 @@ onMounted(loadList);
 2. **行唯一键**：必须显式指定 `:row-config="{ keyField: 'id', useKey: true }"`（`keyField` 与业务主键如 `userCode` 对齐）。
 3. **受控双向绑定**：推荐优先使用 `v-model:selected-row-keys="selectedRowKeys"` 或 `v-model:selected-rows="selectedRows"`，或者统一监听 `@selection-change`。
 4. **批量操作按钮**：放在 `#toolbar-right`，并配置 `:disabled="selectedRowKeys.length === 0"`。
-5. **清空选中态**：批量操作成功后，直接重置 `selectedRowKeys.value = []` 或调用 `tableRef.value.clearSelection()`。
+5. **清空选中态**：批量操作成功后，清空实际受控的 `selectedRowKeys` / `selectedRows`，并在存在表格内部选择缓存时调用已核验的 `tableRef.value.clearSelection()`。受控状态与组件可见勾选必须一致；不能只清其中一层。
 
 ```vue
 <YTable
@@ -244,7 +244,7 @@ onMounted(loadList);
 
 - [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
 - [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
-- [ ] 批量操作成功后已重置 `selectedRowKeys` 并调用 `tableRef.clearSelection()`。
+- [ ] 批量成功后，所有实际受控选择字段与表格可见勾选均已清空；内部缓存存在时已通过 `clearSelection()` 清除。
 - [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
 - [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。
 - [ ] 查询、重置、翻页、刷新和导出复用同一份 `currentParams`；查询/重置回到第一页，批量成功后清空选中态。

package/template/.codex/skills/alibaba-java-code-style/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: alibaba-java-code-style
-description: Apply Alibaba Java Development Manual conventions when implementing, refactoring, or reviewing Java/JVM code, Spring-style services, MyBatis/ORM mappings, SQL, Maven dependencies, unit tests, exception/logging behavior, security checks, and design documentation. Use when the user asks for Java code规范, 阿里规范, P3C-style review, Java code style, or compliance with Alibaba Java coding guidelines.
+description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
 # Alibaba Java Code Style
@@ -16,7 +16,7 @@ This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into
 2. Apply mandatory rules first, then use recommended rules to improve maintainability, performance, and readability.
 3. When reviewing, report mandatory violations as findings. Mention recommended violations when they create real risk or are already in the changed area.
 4. When implementing, prefer the repository's existing framework helpers and code generation skills over inventing new local infrastructure.
-5. If a rule touches a project safety boundary such as auth, payment, encryption, raw SQL, database migration scripts, or public base library API changes, produce a draft or `TODO-HUMAN-REVIEW` rather than silently finalizing risky code.
+5. For auth, payment, encryption, SQL, migrations or public-library changes, check the current contract and actual authorization. Continue an already authorized repair with its required verification; produce a draft or `TODO-HUMAN-REVIEW` only for a real missing decision or approval, and identify that gap.
 
 ## Core Priorities
 

package/template/.codex/skills/archify/SKILL.md

@@ -37,7 +37,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R
 
 1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
 2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
+3. After required source and schema checks, write an early candidate; do not block necessary fact or permission checks merely to make the next tool action a write. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
 4. Validate after every candidate edit and immediately before handoff:
 
    ```bash
@@ -93,24 +93,7 @@ Read Mermaid for topology and meaning, then author fresh Archify JSON; do not me
 
 ## Authoring invariants
 
-- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
-- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
-- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
-- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
-- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
-- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
-- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
-- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
-- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
-- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
-- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
-- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
-- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
-- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
-- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
-- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
-
-Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
+Keep typed source and rendered output consistent; stable IDs and source facts must be traceable. Edges may not cross unrelated opaque nodes, share ambiguous corridors or hide labels. When placing nodes, choosing routes or repairing geometry, read [geometry and routing](references/geometry-and-routing.md). Validate the actual output before delivery.
 
 ## Delivery
 

package/template/.codex/skills/archify/references/geometry-and-routing.md

@@ -0,0 +1,20 @@
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
+- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
+- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
+- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
+- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
+- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
+- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
+- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
+- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
+- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
+- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
+- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
+- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
+- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
+
+Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.

package/template/.codex/skills/code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point. For YSS implementation, Standards must load Slice contract required_skills plus specialist check inputs such as alibaba-java-code-style and yss-ui; do not add a second generic review skill.
+description: 审查分支、PR、固定候选或工作树改动，按仓库规范、Spec 及适用 UI 还原要求报告有证据的缺陷。
 ---
 
 Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
@@ -21,39 +21,9 @@ If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-
 
 ## Process
 
-### 1. Pin the fixed point and candidate
+### 1. 固定候选
 
-Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
-
-Choose one candidate mode from the request or an upstream review contract:
-
-- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
-- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
-  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
-  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
-  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
-  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
-
-Record one **candidate manifest** before review:
-
-```yaml
-review_mode: committed # or worktree
-review_base_ref: <fixed-point>
-merge_base: <resolved-sha>
-implementation_candidate_ref: HEAD # or working-tree
-candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
-candidate_digest: <sha256-or-immutable-tree-id>
-tracked_diff_command: <command>
-untracked_inventory_command: <command-or-null>
-untracked_files: []
-commit_list_command: <command>
-```
-
-For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
-
-For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
-
-Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.
+开始审查前按 [候选捕获合同](references/candidate-capture.md) 选择 committed/worktree 模式，固定比较基点、内容摘要和未跟踪文件。保持只读；候选变化使相关审查失效。
 
 ### 2. Identify the spec source
 

package/template/.codex/skills/code-review/references/candidate-capture.md

@@ -0,0 +1,33 @@
+### 1. Pin the fixed point and candidate
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Choose one candidate mode from the request or an upstream review contract:
+
+- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
+- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
+  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
+  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
+  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
+  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
+
+Record one **candidate manifest** before review:
+
+```yaml
+review_mode: committed # or worktree
+review_base_ref: <fixed-point>
+merge_base: <resolved-sha>
+implementation_candidate_ref: HEAD # or working-tree
+candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
+candidate_digest: <sha256-or-immutable-tree-id>
+tracked_diff_command: <command>
+untracked_inventory_command: <command-or-null>
+untracked_files: []
+commit_list_command: <command>
+```
+
+For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
+
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to the assigned reviewer(s). The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. New captures use a previously nonexistent directory under `.template-source/evidence/maintenance/`, land atomically, and store exactly `candidate-manifest.yaml`, `candidate.bin` and `tracked.diff`; `candidate.bin` already contains every untracked byte, so do not duplicate hundreds of `untracked-content/000xxx` files. Explicit exclusions are fail-closed to `.template-source/evidence/maintenance/` evidence and cannot exclude implementation or authority assets. Historical per-file snapshots remain readable. Every assigned reviewer must consume the captured stream and must not independently treat a live worktree as the reviewed candidate.
+
+Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not during professional review. Do not silently downgrade Worktree review to `HEAD`-only review.

package/template/.codex/skills/code-review/references/yss-review-standards.md

@@ -59,3 +59,23 @@ YSS 页面模块约定（YTable、YFormily、页面骨架等）走 Standards，
 | `drift`、`new_impacts`、`required_skills` 与真实影响不一致 | 合同标 `stale`，回 实现合同编译器 或更早生命周期阶段；禁止在旧合同上继续编码 |
 
 `not-applicable` 仅当影响面未命中。命中后的 mandatory 不得豁免；只允许修复，或写完整 `seam-deferred`（风险、责任人、后续 Ticket、验证计划、目标版本或发布日期）。禁止为日常 Alibaba / YSS 新增生物人豁免门禁；安全 / 公共 API 仍走既有 `TODO-HUMAN-REVIEW` 与生物人门禁。
+
+
+## 可执行后端审查结果
+
+后端 `work-unit.code-review` 到交付的流转由 `scripts/lib/backend-review.mjs` 检查。
+`decision_state.review_input` 绑定 `slice_contract_ref`、`approval_ref`、跨仓时的 `work_unit_id`、`project_root`、既有候选的 `review_mode`、
+`candidate_snapshot_ref`、`implementation_candidate_ref`、`candidate_digest`、
+`implementation_actor_id`、`implementation_instance_id` 和 `actual_skill_impacts`（无新增影响为 `[]`）。
+`review_result_ref` 指向唯一 `code-review` 结果；记录 `result: completed`、合同原始字节的
+`contract_digest`、候选摘要、`reviewer` / `implementer` 的 actor_id / runtime_id / instance_id，
+并分别记录 `axes.Standards` 和 `axes.Spec`。自审不能用不同角色名替代不同执行实例。
+
+复用 `constraint_results`，按派生覆盖清单逐条包含 `constraint_id`、`applicability_basis`、`axis: Standards`、`skill`、`constraint`、`status`、`rule_ref/rule_digest`、`code_ref`、`evidence_ref/evidence_digest`。每个适用技能还须完成 full-text 项并保留具体 `review_notes`。漏技能、漏规则、重复项、过期证据均不能完成。无分页等需求只豁免对应条件规则，不豁免整个适用技能。
+
+后端输入必须增加 `scope_kind: change`、`standards_coverage_ref/digest`；`committed` 候选还绑定 `review_base_ref`。只读存量基线使用 `scope_kind: baseline`，允许无 Slice/无 diff，成功仅为 audited，不能关闭实现审查。详细输入、未知类型与全文核对规则见 `yss-backend-spec-review/references/standards-coverage.md`。未提供结构化覆盖的历史报告只能阅读，不作为新完成证据。
+
+工作树候选复用现有 packed candidate 工具；审查证据可排除，业务文件不可排除。已提交候选绑定
+不可变 tree ID，并核对当前清洁 checkout。读取结构化结果不会代替 Reviewer 的实际规则判断。
+
+`verification_results` 必须包含实际 command、executed_at、exit_code=0、candidate_digest，以及日志 evidence_ref/evidence_digest。缺少本次机器检查或日志漂移不能完成审查。

package/template/.codex/skills/codebase-design/SKILL.md

@@ -9,7 +9,7 @@ Design **deep modules**: a lot of behaviour behind a small interface, placed at
 
 ## Glossary
 
-Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+Use these terms to distinguish concepts in deep-module analysis. Preserve the project's authoritative CONTEXT vocabulary and existing component/service/API/boundary names; this analytical vocabulary does not rename domain concepts.
 
 **Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
 
@@ -62,7 +62,7 @@ When designing an interface, ask:
 - **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
 - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+- **Use variation as evidence for a seam.** Two real adapters are strong evidence, not a mandatory count. A single adapter can still protect an external dependency, a test seam or an explicit change boundary; avoid speculative abstraction without such a reason.
 
 ## Designing for testability
 

package/template/.codex/skills/competitive-intelligence/SKILL.md

@@ -47,7 +47,7 @@ Use this skill when competitive or market facts are needed to shape product Plan
 5. Hand off to lifecycle assets:
    - Update Plan findings in `docs/.scratch/<feature>/plan/`.
    - Create or update a competitor matrix in `docs/.scratch/<feature>/plan/reports/`.
-   - Feed stable user, pain, MVP, non-goal, and success criteria into `grill-with-docs` and `to-spec`.
+   - Return stable user, pain, MVP, non-goal and success criteria to the current lifecycle/strategic owner for its native Plan and Spec work units. Compatibility entries remain explicit-user-only.
    - Record uncertain claims as assumptions, not requirements.
 
 ## Output Shape

package/template/.codex/skills/data-analytics/mcp/server.cjs

@@ -1913,7 +1913,8 @@ function exportDataScienceArtifactPackage(args) {
     archive_path: archivePath,
     worker_entrypoint: path.join(serverDir, "index.js"),
     appgarden_path: path.join(metaDir, "appgarden.json"),
-    access_default: "workspace_all",
+    access_default: null,
+    access_requirement: "explicit-user-selection-before-deployment",
     routes: ["/", "/api/manifest", "/api/snapshot", "/api/package", "/api/source-file", "/api/inline-chart-widget"],
     message:
       "Exported the validated Data Analytics artifact with the canonical MCP app runtime for Site Creator deployment.",

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/SKILL.md

@@ -12,10 +12,13 @@ dashboards, experiments, or downstream pipelines. Start with the intended use an
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ## Workflow
 
+Choose checks from the data grain, intended decision and known risk. Reuse fresh checks already covering the same source/query/transform; do not repeat the catalog. A notebook is needed only when reproducibility or multi-step analysis warrants it. Preserve blocking correctness findings and report material limitations.
+
+
 1. Clarify the quality question and operating context.
 
    Establish what the dataset represents, the intended unit of analysis, the downstream use, whether the user cares about raw ingestion quality,
@@ -26,7 +29,7 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 2. Choose an inspectable analysis path.
 
-   When checks require SQL or Python, default to a companion notebook so the user can inspect the exact code behind the findings. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.
+   When multi-step SQL/Python analysis needs a reproducible narrative, use a companion notebook; a bounded check may provide its query/script and result directly. Use $jupyter-notebooks when a dedicated notebook scaffold or refactor workflow would help. For queryable tables, use `~~structured_data` to confirm schema, grain, sample rows, and query rules through the relevant source connector before heavier checks. Use `~~operations_logs` for freshness and lineage when those checks matter.
 
 3. Build a compact profile.
 
@@ -76,35 +79,9 @@ Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mod
 
 ## Standards
 
-### Core Checks
-
-- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.
-- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.
-- Validity: type conformance after casting; format checks for IDs, emails, URLs,
-  enums, country codes, and timestamps; range checks for measures, percentages,
-  counts, and dates; allowed-values checks for controlled vocabularies.
-- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.
-- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.
-- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.
-- Volume and shape: row-count drift, distinct-count drift, distribution drift,
-  share-of-total drift for major categories, and new or disappeared categories.
-
-### Specific Check Guidance
-
-- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,
-  casing, formatting, or late updates. Report count, share of affected rows,
-  duplicated keys, and whether duplication is isolated to a time range, source,
-  or segment.
-- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.
-- Domain validity: check malformed identifiers, country codes, timestamps,
-  impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.
-- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.
-- Freshness and schema drift: check row-count changes against recent history,
-  lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.
-- Outliers and distribution shifts: use robust methods such as quantiles, MAD,
-  or IQR before defaulting to z-scores. Check sudden changes in mean, median,
-  variance, zero rate, category share, and long-tail behavior.
-- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.
+### 按影响选择检查
+
+先确认 grain、关键字段和决策风险，再按需读取 [质量检查方法](references/quality-checks.md)。对实际使用的字段/关联执行验证；不把全部目录作为每个任务的固定步骤。
 
 ### Severity
 
@@ -145,7 +122,7 @@ For each finding, include:
 - likely cause when known
 - suggested remediation or automated test
 
-When code was used, include or save a notebook containing the key SQL and Python checks and make the notebook path easy to find.
+When code was used, retain the exact queries/scripts and results. Use a notebook when complexity or the requested output calls for one.
 
 ### Defaults
 

package/template/.codex/skills/data-analytics/skills/analyze-data-quality/references/quality-checks.md

@@ -0,0 +1,29 @@
+### Core Checks
+
+- Completeness: null rate by column; null rate by partition, segment, and time bucket; unexpected empty strings or sentinel values; required-column population rate.
+- Uniqueness: exact duplicate rows, duplicate primary keys, duplicate composite keys, and proportion unique for semi-unique fields such as emails or device IDs.
+- Validity: type conformance after casting; format checks for IDs, emails, URLs,
+  enums, country codes, and timestamps; range checks for measures, percentages,
+  counts, and dates; allowed-values checks for controlled vocabularies.
+- Consistency: cross-field rule checks, units or currency consistency, status and timestamp alignment, and agreement between duplicated fields from different sources.
+- Integrity: parent-child key coverage, orphan records, unexpected many-to-many joins, and broken slowly changing dimension joins.
+- Timeliness: freshness lag from source event time to load time, freshness lag from load time to report time, missing recent partitions, and unexplained historical rewrites or backfills.
+- Volume and shape: row-count drift, distinct-count drift, distribution drift,
+  share-of-total drift for major categories, and new or disappeared categories.
+
+### Specific Check Guidance
+
+- Duplicates and keys: check exact duplicates, primary key duplicates, composite key duplicates at the intended grain, and near-duplicates caused by whitespace,
+  casing, formatting, or late updates. Report count, share of affected rows,
+  duplicated keys, and whether duplication is isolated to a time range, source,
+  or segment.
+- Missingness: distinguish acceptable sparsity from broken completeness. Check null rates over time, newly null columns after schema or pipeline changes, and sentinel values such as `''`, `'unknown'`, `'n/a'`, `0`, or `-1`.
+- Domain validity: check malformed identifiers, country codes, timestamps,
+  impossible values, values outside allowed sets, and cross-field contradictions such as `is_cancelled = false` with a non-null `cancelled_at`.
+- Join coverage: when multiple datasets are involved, check foreign keys that do not match a parent table, unexpected one-to-many expansion, coverage loss when joining to dimensions or experiments, and row counts before and after joins.
+- Freshness and schema drift: check row-count changes against recent history,
+  lag on important date columns, added/removed/retyped columns, and shifts in sparsity or cardinality that suggest upstream changes.
+- Outliers and distribution shifts: use robust methods such as quantiles, MAD,
+  or IQR before defaulting to z-scores. Check sudden changes in mean, median,
+  variance, zero rate, category share, and long-tail behavior.
+- Leakage, backfill, and time travel: check features populated before they should exist, future-dated records, late-arriving data causing unstable recent partitions, and backfills that change historical counts without annotation.

package/template/.codex/skills/data-analytics/skills/build-dashboard/SKILL.md

@@ -15,7 +15,7 @@ This skill owns the dashboard brief, delivery-mode selection, metric definitions
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 ### Source Discovery And Verification
 

package/template/.codex/skills/data-analytics/skills/build-report/SKILL.md

@@ -13,7 +13,7 @@ If this skill is selected directly or included by a report-mode workflow, the ru
 
 ### User Context
 
-Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and running its preflight script before answering, searching connectors, retrieving evidence, creating artifacts, or drafting output. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
+Mandatory pre-answer gate: Invoke `data-analytics:user-context` in preflight mode by loading [data-analytics:user-context](../user-context/SKILL.md) and using its read-only preflight before source selection. Reuse the already loaded envelope within the same workflow while the resolved state paths, file digests, request mode and source scope are unchanged; re-read on change, missing context or explicit inspection. Do not look for a callable MCP tool named `data-analytics:user-context`. Use the returned `data_analytics_preflight` envelope as the source of truth for saved context, source-category mapping, semantic-layer registry, onboarding/final-response obligations, and conditional guidance; use saved context and semantic layers as source-selection inputs, not as substitutes for workflow-time reads from connected or provided sources. Do not read or reinterpret raw plugin state files unless preflight fails, declares required content omitted, local shell access is unavailable, or the user explicitly asks for raw state inspection.
 
 Choose exactly one report delivery mode for each run:
 
@@ -90,7 +90,7 @@ Select exactly one delivery mode per run. Do not build an MCP app report and a s
 
    Build the selected surface so it preserves the report reading path, visible titles, evidence order, caveats, and source metadata. Use the delivery-mode specifications in `Report Standards` as implementation guidance for the selected surface, not as a substitute for the report-building workflow.
 
-   If the user asks to share an MCP app report or dashboard as a hosted link, use the artifact app's Site Creator share path after the MCP app is valid. Call `export_artifact_package` to materialize the current manifest, bounded snapshot, package metadata, inline-safe source text, and real MCP artifact runtime into a Site Creator-compatible app; do not hand-roll standalone HTML or publish a viewer that depends on MCP-only host payload state. Follow the `sites-hosting` workflow and default new hosted report access to `workspace_all` unless the user asks for narrower access.
+   If the user asks to share an MCP app report or dashboard as a hosted link, use the artifact app's Site Creator share path after the MCP app is valid. Call `export_artifact_package` to materialize the current manifest, bounded snapshot, package metadata, inline-safe source text, and real MCP artifact runtime into a Site Creator-compatible app; do not hand-roll standalone HTML or publish a viewer that depends on MCP-only host payload state. Follow the `sites-hosting` workflow and use the audience explicitly selected by the user; if unset, keep the report local/private and ask only when sharing is required.
 
    When revising an existing report, treat the current rendered report and source metadata as the starting artifact. Preserve every existing section, visual, table, source, dataset, title, and caveat exactly unless the user explicitly asks to change it or the requested edit makes a narrow dependent update unavoidable. A request to add a section, swap a chart, restyle a visual, or customize one part of the report is not a request to summarize, replace, reorder, or drop the rest of the report. Render the full revised report in the selected surface; do not hand off a section-only, slimmed, or partial replacement artifact when the prior report was complete.
 
@@ -142,7 +142,7 @@ Read [mcp-app-report.md](specifications/mcp-app-report.md) when the selected rep
 - Keep an obvious top-to-bottom report reading path. Do not turn a report into a dashboard grid unless the user asked for a dashboard. Use a single-column document flow by default; half-width visual blocks are acceptable only when labels, series, and interpretation remain readable in the selected surface.
 - Use report markdown blocks for narrative insights and interpretation. Keep chart/table headers neutral, and put takeaways in adjacent narrative blocks rather than hiding the argument inside visual metadata. Markdown blocks are the primary place for the story.
 - Reports should be substantial enough to stand on their own. Do not deliver a report that is mostly a chart/table bundle with a short summary. The reader should be able to understand the answer, evidence, interpretation, caveats, and recommended next step from the narrative itself.
-- Use flexible section names and story-specific ordering, but make sure the report still does the core jobs: answer the user's question directly; explain the metric, cohort, denominator, time window, and comparison basis when they affect interpretation; pair each important number or visual with plain-English interpretation; explain why the finding matters for the decision; state what remains uncertain or could change the conclusion; and include a practical next step when the evidence supports one.
+- Use flexible section names and story-specific ordering, but make sure the report still does the core jobs: answer the user's question directly; explain the metric, cohort, denominator, time window, and comparison basis when they affect interpretation; pair each important number or visual with plain-language interpretation in the user's language; explain why the finding matters for the decision; state what remains uncertain or could change the conclusion; and include a practical next step when the evidence supports one.
 - Use rich markdown beyond the executive summary when it improves scanning:
   bold topic sentences in important body paragraphs, keep recommendations as real markdown lists, and avoid collapsing list items into run-on paragraphs.
 - When using ordered or unordered lists, put each item on its own Markdown line. Do not put `1.`, `2.`, and `3.` items in the same paragraph, and do not leave an intended list item as an unnumbered continuation line.
@@ -183,7 +183,7 @@ Read [mcp-app-report.md](specifications/mcp-app-report.md) when the selected rep
 
 ### Metrics And Language
 
-- Describe metrics in plain English before exposing implementation details.
+- Describe metrics in the user's language before exposing implementation details.
 - Clarify definitions, cohorts, denominators, filters, and comparison baselines before relying on a metric in the report.
 - Choose the most interpretable audience-facing grain: user, account, workspace, task, turn, session, request, revenue, endpoint, customer, org, or another business-facing unit.
 - Put raw numbers in context: percent of an active base, percent of the previous funnel step, percent of total change, comparison to baseline, target, peer segment, or historical range.