create-yss-spec 3.5.6 → 3.5.9

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

@@ -5,13 +5,17 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 
 # yss-web-controller
 
-## 架构分流（先执行）
+## 任务分流
 
-读取当前合同的 architecture_identity 并与工程基线、仓库登记及 Manifest 核对；再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有工程分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其旧分层 guide；组件、安全、批准合同、允许路径及执行证据规则仍共用。
+- 只读审计读取实际入口和现有契约，缺用例 seam、契约或批准证据时记录缺口；不要求先补 Slice、生成 Manifest 或 metadata。
+- 既有整改消费批准且当前的 Slice、冻结 API/no-impact 与稳定用例 seam；缺必要输入回实现合同编译器补齐。
+- 仅新建 CRUD 要求 Web generation contract、metadata 并调用 initialize-only 生成器。认证、回调、Cookie、下载或流式接口可手工适配，不强制 CRUD 脚本或 metadata。
 
-以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
+## 架构分流
+
+将 `architecture_identity` 与当前工程基线和仓库登记核对；仅生成式来源核对脚手架 Manifest，既有来源使用登记及独立工程观测。再且只读取 `references/profiles/<architecture_profile>.md`。生成式分支为 target-domain-model、layered-mvc-service、mvc-data-analysis-v1；既有分支为 existing-domain-driven-maven、existing-layered-mvc-maven。成熟度以注册表为准，不能把 draft 称为受支持。MVC 不执行下文 DDD 专属规则，也不加载其分层 guide；组件、安全、批准合同、允许路径及执行证据规则共用。
 
-本 Skill 同时支持只读审计、既有整改和新建 CRUD 生成。审计读取实际入口和现有契约，缺证据只记录缺口；整改消费批准 Slice、冻结 API/no-impact 与稳定用例 seam；仅新建 CRUD 才要求 Web generation contract、metadata 并调用 initialize-only 生成器。
+以下 Application / Domain Gateway / Infrastructure / Web module 叙述仅适用于 target-domain-model；MVC 的 service/core/repository/server/client 所有权由所选 Profile 引用定义。
 
 ## 何时使用
 
@@ -19,46 +23,9 @@ description: "按冻结合同与稳定 Application 接口生成或重构 YSS Con
 - 用户要根据冻结 OpenAPI 字段合同、metadata 和稳定 Application 接口生成 Request / Response / Controller / WebConvertor。
 - 用户要求统一 Web Adapter 风格、返回值和接口路径。
 
-手工认证、回调、Cookie、下载或流式接口适用本 Skill，但不强制使用 CRUD 脚本或 metadata。
-
-## 实施前置与审计边界
-
-- 只读审计可以记录用例 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`。
-3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
-4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
-5. 运行 `node scripts/generate_controller.mjs`。
-6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
-7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
-
-## 推荐命令
-
-```bash
-node scripts/generate_controller.mjs \
-  --metadata-file /path/metadata.json \
-  --contract-file /path/approved-web-generation-contract.json \
-  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
-  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
-  --base-package com.yss.demo \
-  --module-name demo \
-  --domain-segment example \
-  --web-project-dir /path/demo-adapter/demo-web \
-  --application-service-package com.yss.demo.application.service \
-  --validation-namespace <resolved-platform-namespace>
-```
-
-## 输出预期
-
-- `rest/dto/request/*CreateRequest.java`
-- `rest/dto/request/*UpdateRequest.java`
-- `rest/dto/request/*PageRequest.java`
-- `rest/dto/response/*Response.java`
-- `rest/*Controller.java`
-- `rest/convertor/*WebConvertor.java`
+## 新建 CRUD 生成
+
+仅新建 CRUD 在输入齐备后必须读取 [生成流程与命令](references/crud-generation.md)，核验 schema v2 Web generation contract、metadata、绑定的 wire profile 与允许路径，再运行 initialize-only 生成器并检查完整输出。复杂接口仍按批准合同补足实现，不以生成成功替代行为验证。
 
 ## 约束
 

package/template/.cursor/skills/yss-web-controller/references/crud-generation.md

@@ -0,0 +1,38 @@
+# 新建 CRUD 生成与核验
+
+仅在新建 CRUD 且入口的批准合同、冻结 API 与稳定用例 seam 已齐备时读取。只读审计、既有整改和手工协议适配不运行初始化生成器。以下命令从 Skill 根目录执行；参数消费当前合同与工程平台解析值，示例不授予写入或覆盖权限。
+
+## 新建 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`。
+3. 涉及 DTO / VO / CMD / Query POJO 样板代码时，加载并遵守 `lombok`。
+4. 涉及 Domain / Application Result 到 VO / DTO 或 CMD / Query 到输入模型的转换时，加载并遵守 `mapstruct`。
+5. 运行 `node scripts/generate_controller.mjs`。
+6. 生成后检查路径、命名、返回值包装、Application Service 引用、`@Valid`、Lombok 注解和 MapStruct WebConvertor 是否对齐项目。
+7. 对复杂接口做少量手工修正，不在 skill 中承诺自动覆盖全部业务逻辑。
+
+## 推荐命令
+
+```bash
+node scripts/generate_controller.mjs \
+  --metadata-file /path/metadata.json \
+  --contract-file /path/approved-web-generation-contract.json \
+  --dto-wire-profile-file /path/to/yss-dto/references/openapi-wire-profile.yaml \
+  --scaffold-manifest-file /path/service/.yss/scaffold-generation.json \
+  --base-package com.yss.demo \
+  --module-name demo \
+  --domain-segment example \
+  --web-project-dir /path/demo-adapter/demo-web \
+  --application-service-package com.yss.demo.application.service \
+  --validation-namespace <resolved-platform-namespace>
+```
+
+## 输出预期
+
+- `rest/dto/request/*CreateRequest.java`
+- `rest/dto/request/*UpdateRequest.java`
+- `rest/dto/request/*PageRequest.java`
+- `rest/dto/response/*Response.java`
+- `rest/*Controller.java`
+- `rest/convertor/*WebConvertor.java`

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

@@ -33,7 +33,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 - 行键使用 `:row-config="{ keyField: 'id', useKey: true }"`，不臆造 `row-key` Prop。
 - 新增、导入、批量操作等主按钮直接放入 `#toolbar-right` 或 `#toolbar-left` 插槽即可自动渲染工具栏；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
 - 删除、启停、发布等危险操作使用 `actionConfig.buttons[].isConfirm = true`，不默认使用 `Modal.confirm`。
-- 列配置超过 10 行时放入 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。
+- 纯列配置集中到 `constant.ts`；需要调用组件 Hook 的操作配置使用工厂函数注入回调，禁止在 `constant.ts` 直接引用组件局部的 `openEdit/deleteItem`。按职责和依赖拆分，不用配置行数决定拆分。
 - 远程筛选必须提供稳定 `filters`，设置 `filterMethod: () => true` 禁用本地二次过滤，并监听 `filter-change`。
 - 自适应滚动列表绑定 `:height="tableHeight"`；`pageable`、工具栏分别对应 `withPagination: true`、`withToolbar: true`。纯短表不强制引入高度 Hook。
 - `mutator.ts` 已对网络错误和 `success === false` 统一 `message.error` 并 reject。API Hook 不再检查 `success === false`，不在 `else/catch` 重复 `message.error`；用 `finally` 恢复 loading，让异常继续中断流程。
@@ -55,7 +55,7 @@ description: "配置或修复 YSS UI YTable 的列表查询、列、分页、行
 ## 交付检查清单
 
 - [ ] 分页状态和 `page-change` 参数均使用 `current/pageSize`，未使用 `currentPage`；`filter-change` 与 YTable 真实 API 一致。
-- [ ] 多选列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
+- [ ] 启用多选时，列已配置 `type: 'checkbox'`，已设置 `:row-config="{ keyField: 'xxx', useKey: true }"`，批量按钮绑定了 `selectedRowKeys.length === 0` 禁用。
 - [ ] 批量成功后，所有实际受控选择字段与表格可见勾选均已清空；内部缓存存在时已通过 `clearSelection()` 清除。
 - [ ] 未使用虚构 `request/searchParams/row-key` Props，也未把 `refresh()` 当成远程请求。
 - [ ] 工具栏、字典翻译、操作确认与高度偏移均与实际开关一致。

package/template/.cursor/skills/ytree-usage/SKILL.md

@@ -36,87 +36,9 @@ description: "配置或修复 YSS UI YTree 的字段映射、搜索、选中与
 - 左树右表优先组合 `YSplitPane + YCard + YTree + YTable`；切换节点时同步查询条件并把右表分页重置为第 1 页。
 - 节点删除 API 的错误由 `mutator.ts` 统一提示并 reject；不在 `else/catch` 重复 `message.error`。
 
-## 标准代码骨架
+## 按需示例
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue';
-import { YTree, type YTreeActionItem } from '@yss-ui/components';
-import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
-
-/** 树节点数据。 */
-interface TreeNode {
-  id: string;
-  name: string;
-  children?: TreeNode[];
-}
-
-const emit = defineEmits<{
-  create: [node: TreeNode];
-  edit: [node: TreeNode];
-}>();
-const treeAreaRef = ref<HTMLDivElement>();
-const treeData = ref<TreeNode[]>([]);
-const searchValue = ref('');
-const selectedKeys = ref<Array<string | number>>([]);
-const { treeHeight } = useTreeHeight(treeAreaRef, {
-  extraOffset: YTREE_SEARCH_HEIGHT,
-});
-
-/** 生成当前节点的非危险操作。 */
-const getNodeActions = (): YTreeActionItem[] => [
-  { key: 'add', label: '新增子节点' },
-  { key: 'edit', label: '编辑' },
-];
-
-/** 处理 YTree 动作事件。 */
-const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
-  if (key === 'add') emit('create', node);
-  if (key === 'edit') emit('edit', node);
-};
-</script>
-
-<template>
-  <div ref="treeAreaRef" class="tree-area">
-    <YTree
-      :height="treeHeight"
-      :tree-data="treeData"
-      :field-names="{ title: 'name', key: 'id', children: 'children' }"
-      filterable
-      show-actions
-      v-model:searchValue="searchValue"
-      v-model:selectedKeys="selectedKeys"
-      :get-node-actions="getNodeActions"
-      @action="handleTreeAction"
-    />
-  </div>
-</template>
-
-<style scoped lang="less">
-@import './style.less';
-</style>
-```
-
-```less
-/* style.less */
-.tree-area {
-  flex: 1;
-  min-height: 0;
-  overflow: hidden;
-}
-```
-
-## 删除确认边界
-
-```vue
-<template #node-suffix="{ node }">
-  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
-    <YButton type="link" @click.stop>删除</YButton>
-  </Popconfirm>
-</template>
-```
-
-`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。
+首次组合受控树、高度与节点动作，或实现删除确认时，读取 [树与删除确认示例](references/tree-and-confirmation-example.md)。简单字段映射修改无需加载整段示例。
 
 ## 交付检查清单
 

package/template/.cursor/skills/ytree-usage/references/tree-and-confirmation-example.md

@@ -0,0 +1,81 @@
+## 标准代码骨架
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { YTree, type YTreeActionItem } from '@yss-ui/components';
+import { useTreeHeight, YTREE_SEARCH_HEIGHT } from '@yss-ui/hooks';
+
+/** 树节点数据。 */
+interface TreeNode {
+  id: string;
+  name: string;
+  children?: TreeNode[];
+}
+
+const emit = defineEmits<{
+  create: [node: TreeNode];
+  edit: [node: TreeNode];
+}>();
+const treeAreaRef = ref<HTMLDivElement>();
+const treeData = ref<TreeNode[]>([]);
+const searchValue = ref('');
+const selectedKeys = ref<Array<string | number>>([]);
+const { treeHeight } = useTreeHeight(treeAreaRef, {
+  extraOffset: YTREE_SEARCH_HEIGHT,
+});
+
+/** 生成当前节点的非危险操作。 */
+const getNodeActions = (): YTreeActionItem[] => [
+  { key: 'add', label: '新增子节点' },
+  { key: 'edit', label: '编辑' },
+];
+
+/** 处理 YTree 动作事件。 */
+const handleTreeAction = ({ key, node }: { key: string; node: TreeNode }) => {
+  if (key === 'add') emit('create', node);
+  if (key === 'edit') emit('edit', node);
+};
+</script>
+
+<template>
+  <div ref="treeAreaRef" class="tree-area">
+    <YTree
+      :height="treeHeight"
+      :tree-data="treeData"
+      :field-names="{ title: 'name', key: 'id', children: 'children' }"
+      filterable
+      show-actions
+      v-model:searchValue="searchValue"
+      v-model:selectedKeys="selectedKeys"
+      :get-node-actions="getNodeActions"
+      @action="handleTreeAction"
+    />
+  </div>
+</template>
+
+<style scoped lang="less">
+@import './style.less';
+</style>
+```
+
+```less
+/* style.less */
+.tree-area {
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+}
+```
+
+## 删除确认边界
+
+```vue
+<template #node-suffix="{ node }">
+  <Popconfirm title="确认删除该节点吗？" ok-text="确定" cancel-text="取消" @confirm="handleDelete(node)">
+    <YButton type="link" @click.stop>删除</YButton>
+  </Popconfirm>
+</template>
+```
+
+`Popconfirm` 从 `ant-design-vue` 导入，`YButton` 从 `@yss-ui/components` 导入。如果每个节点都展示删除会过密，把同样的 `Popconfirm` 放到选中节点的页面工具栏。

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

@@ -3,50 +3,44 @@ name: alibaba-java-code-style
 description: 应用阿里巴巴 Java 手册审查或实现 Java 代码；按当前项目框架与数据库基线选择适用规范。
 ---
 
-# Alibaba Java Code Style
+# 阿里巴巴 Java 规范
 
-This skill distills the provided `阿里巴巴 Java 开发手册` 1.4.0 PDF into execution rules for Codex. Treat rules marked mandatory as review blockers unless the repository's own `AGENTS.md`, security constraints, or existing framework conventions explicitly require a different pattern.
+本 Skill 从用户提供的《阿里巴巴 Java 开发手册》1.4.0 提炼适用规范。`mandatory` 违规阻断审查，除非仓库 `AGENTS.md`、安全约束或现有框架约定明确要求不同模式；例外须有依据。`recommended` / `reference` 保留建议等级，不因进入下文检查提要变为强制规则。
 
-## Workflow
+## 工作流
 
-1. Identify the touched surface:
-   - Java source, naming, constants, OOP, collections, concurrency, control flow, comments: read `references/java-programming.md`.
-   - Exceptions, logging, unit tests, or security: read `references/reliability-test-security.md`.
-   - MySQL, ORM/MyBatis, Maven dependencies, layering, server/JVM settings, or design artifacts: read `references/database-engineering-design.md`.
-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. 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.
+1. 按影响面读取对应规范：Java 命名、常量、OOP、集合、并发、控制流和注释读 [Java 编程](references/java-programming.md)；异常、日志、测试或安全读 [可靠性与安全](references/reliability-test-security.md)；MySQL、ORM/MyBatis、Maven、分层、服务器/JVM 或设计资产读 [工程与数据库](references/database-engineering-design.md)。
+2. 先执行适用 mandatory，再按实际风险采用 recommended；审查报告保留规则等级。建议仅在产生真实风险或处于本次范围时报告。
+3. 实现优先复用工程框架与已有生成能力，不新增重复基础设施。
+4. 认证、付款、加密、SQL、迁移或公共库变更先核验当前合同及实际授权。已授权修复继续完成适用验证；仅真实缺决定或批准时形成草案 / `TODO-HUMAN-REVIEW`，并说明缺口。
 
-## Core Priorities
+## 适用原则
 
 - 先消费 architecture_identity 与工程 Java/数据库基线。MVC 分层按 `.template-spec/agents/backend-architecture-profiles.md`；MySQL 专属方言规则仅对批准的 MySQL 存储生效，不能要求 H2 骨架引入 MySQL 驱动。YSS 包装、命名及处理器差异逐项记录基线例外，安全、权限、敏感信息与 SQL 参数绑定不得豁免。
-- Keep names readable, English, and consistent with Java layer conventions.
-- Avoid null, equality, wrapper comparison, collection, and concurrency traps that compile cleanly but fail at runtime.
-- Make logs useful without wasting CPU, disk, or alert budget.
-- Keep unit tests automatic, independent, repeatable, and close to public behavior.
-- Bind SQL parameters, define explicit ORM mappings, and never rely on string-concatenated SQL.
-- Preserve layering: web/controller code validates and adapts; service/manager code owns business orchestration; DAO/repository code owns persistence.
-
-## Review Checklist
-
-- Naming and formatting are consistent: camel case, constants, package names, braces, spacing, line length, UTF-8/Unix line endings.
-- POJO, DTO, DO, VO, Query, enum, interface, implementation, and test names follow the expected suffixes and boolean naming rules.
-- `equals`, `hashCode`, wrapper comparisons, `toString`, `serialVersionUID`, constructors, access modifiers, and getters/setters avoid known pitfalls.
-- Collection code avoids unsafe `subList`, `Arrays.asList`, raw `toArray`, foreach removal, null-unsafe maps, and invalid comparators.
-- Thread code uses named thread pools, avoids `Executors` factories in production code, and handles locking order, date formatting, and scheduled tasks safely.
-- Exceptions are handled at the right layer, logged once with context and stack, and never swallowed or used for normal control flow.
-- Tests use assertions, avoid external dependence, live under `src/test/java`, and cover boundaries, correct cases, design cases, and error cases.
-- Security-sensitive inputs are validated, authorized, escaped, CSRF-protected, rate-limited, and never concatenated into SQL.
-- MySQL DDL/SQL/ORM code uses explicit fields, mappings, indexes, timestamps, `#{}`
-  parameter binding, and avoids dangerous cascades, stored procedures, `select *`, and uncontrolled pagination.
-
-## Source
-
-Based on the user-provided PDF: `阿里巴巴 Java 开发手册` version 1.4.0, Alibaba Group technical team, update date 2018-05-20.
+- 名称使用清晰英文标识并遵循当前 Java 分层约定。
+- 核验 null、相等、包装类型比较、集合和并发的运行时边界，不能以编译通过代替行为正确。
+- 日志有诊断用途，并控制 CPU、磁盘和告警成本。
+- 单元测试自动、独立、可重复，围绕公开行为验证。
+- SQL 使用参数绑定与显式 ORM 映射，不依赖字符串拼接。
+- 按已登记架构保持职责：Web/controller 校验和适配，service/manager 编排业务，DAO/repository 持有持久化。
+
+## 检查提要
+
+- 命名与格式：camel case、常量、包名、括号、间距、行长、UTF-8/Unix 换行；类型后缀和 boolean 命名符合适用规范。
+- 对象语义：`equals/hashCode`、包装类型比较、`toString`、`serialVersionUID`、构造器、可见性和访问器。
+- 集合：`subList`、`Arrays.asList`、`toArray`、foreach 删除、null map 和 comparator 的边界。
+- 并发：命名线程池、生产 `Executors` 工厂限制、锁顺序、日期格式和定时任务。
+- 异常：正确分层、上下文与堆栈、避免重复日志、不吞异常、不用于普通控制流。
+- 测试：断言、外部依赖隔离、`src/test/java` 与边界/正确/设计/错误场景。
+- 安全：按真实输入与认证方式核验校验、授权、转义、CSRF、限流和 SQL 参数绑定，不能泛用某项检查豁免其他风险。
+- MySQL：仅适用存储核验显式字段、映射、索引、时间戳与 `#{}` 绑定，以及危险级联、存储过程、`select *` 和分页边界。
+
+## 来源
+
+用户提供的《阿里巴巴 Java 开发手册》1.4.0，阿里巴巴集团技术团队，更新于 2018-05-20；具体条款等级保留在对应 references 中。
 
 ## 阶段 7 执行结果
 
 - 消费当前合同版本、changed files 和 verification results，只审查合同允许范围。
-- 必须把 mandatory violation 返回为 `violation`，并提供文件/位置/规则证据；高风险项保留 `TODO-HUMAN-REVIEW`。
+- 适用 mandatory violation 返回 `violation`，附文件/位置/规则证据；高风险项仅在当前合同确有未满足人工决定或批准要求时保留 `TODO-HUMAN-REVIEW`。
 - 按统一 `YSS Skill Execution Result` 返回审查证据、偏离和新增安全/SQL/公共 API 影响，不得仅输出“符合规范”。

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

@@ -25,10 +25,10 @@ When the current repository contains `yss-project.yaml`, these rules override th
   node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json docs/architecture/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
 
   # template-source
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.archify.json .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
+  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.archify.json)" "$(scripts/maintenance-path diagrams/<diagram-id>/<diagram-id>.html)" --quality showcase
   ```
 
-- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use `.template-source/evidence/maintenance/diagrams/<diagram-id>/`. The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
+- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use the current workspace's external `maintenance:diagrams/<diagram-id>/` (resolve with `scripts/maintenance-path`). The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
 - The safe wrapper rejects `--open`, non-HTML targets, symlink escapes, unrelated existing files, and stable source/output pairs outside those roots. Do not bypass it with the raw `deliver` or `preview` commands in a YSS repository.
 
 ## Fast authoring path

package/template/.pi/skills/archify/scripts/yss-safe-deliver.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
 const skillRoot = path.resolve(scriptDirectory, '..');
@@ -93,11 +93,12 @@ function assertReplaceableReceipt(receipt) {
   if (parsed?.yssArchifyReceipt !== true) fail(`拒绝覆盖非 YSS Archify receipt: ${receipt}`);
 }
 
-function stableContract(projectRoot, mode, input, output) {
+async function stableContract(projectRoot, mode, input, output) {
   const relativeBase = mode === 'project-instance'
     ? 'docs/architecture/diagrams'
-    : '.template-source/evidence/maintenance/diagrams';
-  const base = path.join(projectRoot, relativeBase);
+    : 'maintenance:diagrams';
+  const base = mode === 'project-instance' ? path.join(projectRoot, relativeBase)
+    : (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput(relativeBase, { root: projectRoot });
   const relativeOutput = path.relative(base, output);
   const segments = relativeOutput.split(path.sep);
   if (segments.length !== 2 || !diagramIdPattern.test(segments[0])) {
@@ -139,7 +140,10 @@ const temporaryBase = fs.realpathSync(os.tmpdir());
 // parent symlink resolves into the OS temporary directory. Otherwise the
 // temporary-delivery exception could be used to escape the stable output root.
 const requestedWithinProject = requestedProjectRoot !== null;
-const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output);
+const projectMode = projectRoot ? repositoryMode(projectRoot) : null;
+const templateDiagramBase = projectMode === 'template-source'
+  ? (await import(pathToFileURL(path.join(projectRoot, 'scripts/lib/maintenance-storage.mjs')).href)).resolveMaintenanceOutput('maintenance:diagrams', { root: projectRoot }) : null;
+const isTemporary = !requestedWithinProject && isWithin(temporaryBase, output) && !(templateDiagramBase && isWithin(templateDiagramBase, output));
 let mode = null;
 let receipt;
 let allowedBase;
@@ -150,7 +154,7 @@ if (isTemporary) {
 } else {
   if (!projectRoot) fail('稳定交付必须从包含 yss-project.yaml 的仓库内运行');
   mode = repositoryMode(projectRoot);
-  const contract = stableContract(projectRoot, mode, input, output);
+  const contract = await stableContract(projectRoot, mode, input, output);
   allowedBase = contract.base;
   receipt = contract.receipt;
 }

package/template/.pi/skills/archify/test/yss-safe-deliver.test.mjs

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import test from 'node:test';
+import { resolveMaintenanceOutput } from '../../../../scripts/lib/maintenance-storage.mjs';
 import { fileURLToPath } from 'node:url';
 
 const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -12,6 +13,12 @@ const example = path.join(skillRoot, 'examples', 'web-app.architecture.json');
 
 function repository(mode = 'project-instance') {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), 'yss-archify-safe-'));
+  if (mode === 'template-source') {
+    fs.mkdirSync(path.join(root, 'scripts/lib'), { recursive: true });
+    for (const name of ['maintenance-storage.mjs', 'runtime-store.mjs', 'repository-mode.mjs']) fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/lib', name), path.join(root, 'scripts/lib', name));
+    fs.mkdirSync(path.join(root, 'scripts/vendor'), { recursive: true });
+    fs.copyFileSync(path.resolve(skillRoot, '../../../scripts/vendor/yaml.mjs'), path.join(root, 'scripts/vendor/yaml.mjs'));
+  }
   fs.writeFileSync(path.join(root, 'yss-project.yaml'), `schema_version: 1\nrepository_mode: ${mode}\n`);
   return root;
 }
@@ -104,9 +111,9 @@ test('delivers a paired project artifact and an auditable receipt', () => {
   assert.equal(receipt.archify.validation.warnings, 0);
 });
 
-test('uses the template-source evidence root for stable maintenance diagrams', () => {
+test('uses the external workspace maintenance root for stable diagrams', () => {
   const root = repository('template-source');
-  const directory = path.join(root, '.template-source', 'evidence', 'maintenance', 'diagrams', 'workflow-map');
+  const directory = resolveMaintenanceOutput('maintenance:diagrams/workflow-map', { root });
   fs.mkdirSync(directory, { recursive: true });
   const input = path.join(directory, 'workflow-map.archify.json');
   const output = path.join(directory, 'workflow-map.html');

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

@@ -3,7 +3,7 @@ name: code-review
 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:
+Review a pinned candidate: all applicable axes initially, then affected conclusions and dependencies:
 
 - **Standards** — does the code conform to this repo's documented coding standards **and**, for YSS slices, the specialist check inputs compiled in [yss-review-standards.md](references/yss-review-standards.md)?
 - **Spec** — does the code faithfully implement the originating issue / spec?
@@ -11,13 +11,13 @@ Review of a pinned candidate against a fixed point on two core axes, plus UI fid
 
 普通功能默认由一名与实现者独立的审查者完成 Standards、Spec 和适用的 UI fidelity 检查，分别报告结论。只有专业能力缺口、结论冲突、明确外部制度或用户指定时，才拆成多个审查者；多个无依赖审查可以并行。检查轴不等于会签人数，不能要求用户为每个轴重复确认。
 
-If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+角色表编译 `review_context` / `skill_source.review_skills`（只读）；见协作规则，不授予实现权限。
 
-文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
+If `.template-spec/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
 
 ## 文档写作
 
-撰写审查报告时，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。
+撰写审查报告时，按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `.template-spec/process/document-writing.md` 的共用写法及审查指引；保留各审查轴的 findings、严重性、定位、证据及原裁决，不因压缩表达合并或降级。作用域仅限当前产物，派发时传递条件及引用。
 
 ## Process
 
@@ -38,27 +38,35 @@ Look for the originating spec, in this order:
 
 Compile sources **before** review. For YSS implementation candidates follow [yss-review-standards.md](references/yss-review-standards.md): run machine checks that exist in the implementation repo; then collect repo docs (`CODING_STANDARDS.md` / `CONTRIBUTING.md` if present), every Slice `required_skills` skill file, the impact-conditioned specialist inputs (`alibaba-java-code-style`, `yss-ui`, `yss-domain`, …), and `.template-spec/templates/review-report-template.md`. Missing applicable coverage is `missing_evidence`, not a pass.
 
-For YSS backend review, derive the review roots from the candidate project root, implementation-repository registry, Slice `project_roots` and `allowed_write_paths`. Review only the project itself and registered backend development projects; exclude frontend roots, unrelated submodules/vendor trees and unregistered directories. Never replace this resolution with a fixed `apps/backend` assumption.
+Resolve backend roots from the registered project and Slice scope; exclude frontend, vendor, unrelated submodules and unregistered roots. Assess both `yss-repository` and `yss-mybatis` for every backend candidate, including impact, selected Profile and current component source index per the standards reference. Without persistence impact, record concrete `not-applicable` reasons for both.
 
-Every backend candidate must explicitly assess `yss-repository` and `yss-mybatis`. When the candidate changes persistence structure, Mapper/XML, SQL, pagination, batch operations, scanning/configuration or data-source behavior, read both skills and the selected Repository Profile; exact component claims also require a current `yss-mybatis` source index. When no persistence impact exists, record a concrete `not-applicable` reason for both instead of silently skipping them.
-
-Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`, remains a source. It does **not** replace YSS or Alibaba specialist inputs.
+Repo coding documents remain sources alongside mandatory YSS / Alibaba inputs.
 
 Standards 检查代码 diff 时读取 [Fowler smell baseline](references/smell-baseline.md)。仓库明确标准优先；smell 只作 judgement call，不升级为硬违规，机器已覆盖项不重复判断。
 
 ### 4. Complete each applicable review axis
 
-默认由当前独立 Reviewer 连续完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
+默认由独立 Reviewer 完成下列两份检查提纲，按轴保留结论，不派发额外 subagent。需要多专业参与时，按角色表和协作协议派发对应提纲；只增加缺少的能力，不默认启动两个额外 Agent。下面的 sub-agent prompts 同样是单 Reviewer 的检查清单。
 
 执行 Standards / Spec 轴时读取 [逐轴检查提纲](references/review-axis-checklists.md)；单 Reviewer 同样使用它。实际派发时传入相同候选、证据和完整 smell baseline；Spec 缺失按提纲明确报告。
 
-普通审查只复验修复影响的结论及其依赖；候选摘要变化后仍须重新绑定当前候选，不能沿用过期证据。未受影响项记录依据后复用。已明确采用下节历史候选/多轴合同的审查继续遵守其约定。
+首轮完整覆盖；修复后依差异、受影响结论 / 行为及依赖定向复验并绑定当前候选，未受影响项有依据地复用。摘要、UI 或 `new_impacts` 不触发全轴兜底，未知先调查。历史两轮同样适用；细则见 [finding 闭环](references/yss-review-standards.md)。
 
 ### 5. Aggregate
 
 仅任务包携带 `review_round`、明确采用历史冻结候选协议时，读取 [两轮收敛合同](references/legacy-convergence.md)。普通审查不因此新增候选冻结或额外审查者。
 
-Present the reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Fill `.template-spec/templates/review-report-template.md` specialist tables as part of Standards evidence, not a fourth axis. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_). A YSS candidate with blank applicable specialist rows, skipped `required_skills`, or unaddressed mandatory violations is `blocked`, not `completed`. Do not close findings by writing implementation in the review session. `violation` / machine-check failure / blank applicable rows go back to the implementer on the original contract path, then recapture the candidate and rerun affected axes and their dependencies; explicitly rebind unchanged evidence. `drift` / `new_impacts` / `required_skills` mismatch mark the contract `stale` and return to 实现合同编译器; do not keep coding on the old contract. `not-applicable` is only for untriggered impacts; mandatory gates have no waiver, only repair or a complete `seam-deferred` record.
+#### 报告与阻断
+
+按 `## Standards`、`## Spec` 分别呈现原报告或等义整理后的结论；UI 影响另列 `## UI fidelity`。专项表填写在 `.template-spec/templates/review-report-template.md` 的 Standards 证据中，不增加第四轴，也不合并或跨轴重排 findings。适用专项行空白、遗漏 `required_skills` 或 mandatory violation 未关闭时，结果为 `blocked`，不能写 `completed`。
+
+#### 修复后复审
+
+Reviewer 保持只读，将 `violation`、机器检查失败和适用行空白交回原合同路径的实施者。修复后比较差异、重新捕获候选，复审受影响结论与依赖，并明确重新绑定未受影响的证据；不在审查会话中写实现来关闭 finding。
+
+#### 合同失效与延期
+
+`drift`、`new_impacts` 或 `required_skills` 不匹配时，将合同标为 `stale` 并回到 实现合同编译器 调查受影响要求；停止使用旧合同实现，不默认全轴重审。`not-applicable` 只用于未触发影响。mandatory 门禁不能豁免；按原合同修复，或在原流程允许延期时提供完整 `seam-deferred` 记录。
 
 For Worktree mode, recapture the candidate digest after all applicable checks finish. If it differs from `candidate_digest`, mark the affected reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
 

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

@@ -28,6 +28,6 @@ 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.
+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 template-maintenance captures use a previously nonexistent external `maintenance:candidates/<id>/` directory, resolved through the workspace maintenance storage, 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. New template-maintenance captures reject explicit exclusions: the historical archive-path allowlist is retired, and maintenance material lives outside the repository. Historical schema v1 exclusion lists remain read-only compatible. Candidate manifest schema v2 uses `reference_base: bundle`, the workspace identity, and package-relative stream/diff references. The original candidate byte stream and digest remain unchanged; schema v1 remains read-only compatible. Project-instance and Slice candidates keep their registered repository scope and existing path permissions; the maintenance capture CLI does not grant external paths to them. 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/.pi/skills/code-review/references/legacy-convergence.md

@@ -2,4 +2,6 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
-For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. Round 1 blocking findings return to the implementer and require a new digest plus all review axes. If Round 2 still has an open `violation`, `drift`, or `new_impacts`, return `needs-human` and stop; do not silently start Round 3. Candidate byte changes invalidate every earlier axis report.
+For template-maintenance task packages carrying `review_round`, preserve the frozen scope and apply the two-round convergence contract. A hard requirement added during review must cite a rule that already applied when the candidate was frozen; otherwise report it as `judgement-call` for the backlog. First review covers all applicable checks. After Round 1 repairs, compare the old and new candidates, identify affected conclusions, behavior and dependencies, rereview only that scope, and bind every consumed conclusion to the new digest. Candidate byte changes invalidate the old candidate binding, not every underlying conclusion; reuse requires readable comparison evidence showing unchanged conditions, basis and dependencies. UI impact, `new_impacts` or unknown impact never selects all axes by default or as a fallback; investigate unknown impact before selecting the rereview scope.
+
+For this explicitly selected legacy contract, if Round 2 still has an open `violation`, `drift` or `new_impacts`, the existing evaluator returns `needs-human`; do not silently start Round 3 or rewrite historical states. This compatibility limit is not enabled for ordinary review. Return the unresolved findings and readable evidence to the orchestrator, which separates professional wait, repair / rerouting and missing real decisions, and continues independent authorized work. A new user request still requires a real missing decision or authorization and reviewable assets. No prior approval or report is rewritten.

package/template/.pi/skills/code-review/references/review-axis-checklists.md

@@ -2,6 +2,8 @@
 
 仅在入口所列条件命中时读取本文件。Markdown 链接相对本文件；行内 references/assets/schemas 路径相对 Skill 根目录。仓库脚本与 pnpm 命令从当前登记的项目根目录执行。
 
+首轮完整覆盖每个适用轴。复审任务额外传入旧 / 新候选差异、受影响结论与行为、直接 / 传递依赖和待复验清单；下列提纲按该清单使用，未受影响结论保留比较证据并绑定当前候选。摘要变化、UI 或 `new_impacts` 不自动选择全部提纲；未知影响先调查。
+
 **Standards sub-agent prompt** — include:
 
 - The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.