create-yss-spec 3.4.8 → 3.4.10

package/template/.pi/skills/yss-repository/tests/profile-routing.test.mjs

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { access, readFile, readdir } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
+import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { fileURLToPath } from "node:url";
 
 const repositorySkillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -15,7 +16,8 @@ async function text(target) {
 test("repository router exposes exactly the registered profile entry points", async () => {
   const profilesRoot = path.join(repositorySkillRoot, "references/profiles");
   const profiles = (await readdir(profilesRoot)).filter((name) => name.endsWith(".md")).sort();
-  assert.deepEqual(profiles, ["layered-mvc-service.md", "mvc-data-analysis-v1.md", "target-domain-model.md"]);
+  const registry = parseDocument(await text(path.join(projectRoot, "docs/agents/yss-skill-registry.yaml"))).toJS();
+  assert.deepEqual(profiles, [...Object.keys(registry.architecture_profiles), ...Object.keys(registry.existing_project_profiles)].map(id => `${id}.md`).sort());
 
   const skill = await text(path.join(repositorySkillRoot, "SKILL.md"));
   for (const profile of profiles) assert.match(skill, new RegExp(`references/profiles/${profile.replace(".md", "")}`));

package/template/.pi/skills/yss-stage-decision/SKILL.md

@@ -5,6 +5,8 @@ description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作
 
 # YSS Stage Decision
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 `yss-stage-decision` 是由生命周期主控调度的上游决策技能，负责把需求、产品、商务输入和业务边界与规则设计结果整理成可审查、可版本化、可被下游消费的方案决策包。它不替代生命周期主控，也不生成产品代码、原型、OpenAPI 或垂直切片 Ticket。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。
@@ -69,4 +71,4 @@ Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有
 
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+跨仓交付或恢复时读取 [战略交接合同](references/strategic-handoff-routing.md)。只接受当前可核验包与承接结果；用户决定、版本失效和批准边界仍由主控持有。

package/template/.pi/skills/yss-stage-decision/references/strategic-handoff-routing.md

@@ -0,0 +1,3 @@
+## 战略交接快照包
+
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。

package/template/.pi/skills/yss-tactical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 # yss-tactical-design
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 本 skill 负责 DDD 战术设计，不新增生命周期主阶段，也不替代 `yss-stage-decision` 或 `yss-domain`。
 
 ## 适用边界
@@ -36,9 +38,7 @@ description: 在 YSS 技术分析阶段将批准的战略领域输入细化为
 
 ## 战略交接快照包
 
-跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
-
-战术合同必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。
+仅在输入来自战略交接包时，读取 [战略承接核验](references/strategic-handoff-routing.md)，绑定收据、摘要和逐规则承接；源变化或未知依赖阻断并回交主控。
 
 ## 后端脚手架平台承接
 

package/template/.pi/skills/yss-tactical-design/references/strategic-handoff-routing.md

@@ -0,0 +1,5 @@
+## 战略交接快照包
+
+跨仓交接使用 `scripts/strategic-handoff export / verify / import`。正式导出前补齐源战略的稳定规则 ID、关键场景和当前批准绑定；源资产原字节冻结、包内路径通过清单解析。目标导入只产生快照和对账/承接草案，正式 reconciliation 通过后才能进入战术设计。流程与字段见 `docs/process/strategic-handoff-package.md`。
+
+战术合同必须绑定 `strategic_handoff` 导入收据、包摘要、正式目标对账及逐条承接 rows。来自导入包时禁止仅填 `upstream_current: true`。批准前执行 `scripts/verify-strategic-handoff-consumption --root <target> <tactical>`；存在受控延期时按切片执行 `--slice <slice-id>`，实际核验通过且合同批准后才可继续相关切片。最新源规则、关键场景或资产变化使依赖项 stale；未知依赖扩大阻断，业务冲突回交战略方。结果绑定当前包与战术摘要，不能复用旧输出宣布 ready-for-agent。

package/template/.pi/skills/yss-technical-design/SKILL.md

@@ -5,6 +5,8 @@ description: 在 YSS 技术分析中统一承接需求与战略输入，按已
 
 # YSS 技术设计
 
+已有生命周期资产优先用 `scripts/contract view <资产> --kind <类型>` 阅读；执行任务用 `--profile task --unit <ID>`，绑定与校验明细用 `--profile full`。视图不授予执行权限，仍按本 Skill 的原始来源和批准门禁处理。类型、准备和迁移见 `docs/process/contract-reading.md`。
+
 由 `yss-product-lifecycle` 调度，负责 `work-unit.technical-analysis` 的技术设计，不另起生命周期、不生成生产代码。生命周期维护批准和状态；`yss-implementation-contract-compiler` 消费批准且当前的设计，起草实现合同。
 
 文档输出时按 `lifecycle-document-output` 条件调用 `i-have-adhd`，读取 `docs/process/document-writing.md`；作用域仅限当前产物，派发时传递条件及引用。

package/template/.pi/skills/yss-technical-design/scripts/engineering-design.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import {readFileSync} from 'node:fs';
+import {readFileSync} from '../../../../scripts/lib/validation-phase.mjs';
 import {ensure,read,safe,hash} from '../../../../scripts/lib/strategic-handoff-io.mjs';
 const beneath=(ref,scope)=>ref===scope||ref.startsWith(`${scope}/`);
 export function validateEngineeringDesign(data,{root}) {

package/template/.pi/skills/yss-technical-design/scripts/validate-technical-design.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
+import { readFileSync, withValidationPhase, validationDependencies } from '../../../../scripts/lib/validation-phase.mjs';
 import { validateEngineeringDesign } from './engineering-design.mjs';
 import { createApprovedExecutionContext, assertApprovedExecutionContext } from '../../../../scripts/lib/approved-execution-context.mjs';
 import { verifyArchitectureEvidence } from '../../../../scripts/lib/backend-architecture.mjs';
@@ -42,8 +42,8 @@ function validateMvc(design) {
   if (!design.integration_catalog.length) ensure(text(design.integration_not_applicable_reason), '无外部集成必须说明原因');
 }
 
-export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
-  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef});
+export function verifyArchitecture(data, root, {execution,sliceRef,readOnly=false}={}) {
+  if(execution)assertApprovedExecutionContext(execution,{root,technicalDesign:data,sliceId:sliceRef,readOnly});
   const binding = data.architecture;
   const file = safe(root, binding.decision_ref);
   ensure(hash(readFileSync(file)) === binding.decision_digest, '架构来源摘要漂移');
@@ -63,7 +63,7 @@ export function verifyArchitecture(data, root, {execution,sliceRef}={}) {
     ensure(!['stale','blocked'].includes(record.status) && !['stale','blocked'].includes(entry.status), '工程登记已失效');
     if (entry.architecture_identity?.schema_version === 2) {
       ensure(entry.architecture_evidence?.engineering_baseline && entry.architecture_evidence?.manifest, '既有工程登记缺少原始工程证据引用');
-      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution });
+      verifyArchitectureEvidence(entry.architecture_identity, { ...entry.architecture_evidence, repository_registration: { ref: binding.decision_ref, digest: binding.decision_digest } }, { root, execution, readOnly });
     }
   }
 }
@@ -111,7 +111,7 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
   ensure(data.digest === technicalDigest(data), '技术设计合同摘要不匹配');
   ensure(!['stale','blocked','drift','new_impacts'].includes(data.status), '设计状态不可消费');
   if (sliceRef) ensure(data.status === 'approved', '切片只能消费 approved 设计');
-  verifyArchitecture(data, root, {execution,sliceRef});
+  verifyArchitecture(data, root, {execution,sliceRef,readOnly});
   ensure(data.inputs.some(item => item.kind === 'context' && item.ref === 'CONTEXT.md') && data.inputs.some(item => item.kind === 'spec'), '共同输入缺少根 CONTEXT.md 或 Spec');
   for (const input of data.inputs) ensure(hash(readFileSync(safe(root, input.ref))) === input.digest, `输入摘要漂移: ${input.ref}`);
   for (const ref of data.evidence_refs) safe(root, ref);
@@ -135,12 +135,15 @@ export async function validateTechnicalDesign(data, { root = process.cwd(), slic
 }
 
 async function main() {
-  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
+  const { values, positionals } = parseArgs({ allowPositionals: true, options: { root: { type: 'string', default: process.cwd() }, slice: { type: 'string' }, 'legacy-ddd': { type: 'boolean', default: false }, 'read-only': {type:'boolean',default:false}, 'validation-dependencies': {type:'boolean',default:false}, 'work-unit': {type:'string'}, 'approved-slice': {type:'string'}, 'approved-slice-digest': {type:'string'}, 'approved-slice-approval': {type:'string'} } });
   ensure(positionals.length === 1, '用法: validate-technical-design.mjs <合同> --root <项目根> [--slice <ID>] [--legacy-ddd]');
   const approvedOptions=['approved-slice','approved-slice-digest','approved-slice-approval'];
   ensure(!approvedOptions.some(key=>values[key])||approvedOptions.every(key=>values[key]),'执行增量必须完整给出持久化 Slice、字节摘要及本地批准引用');
-  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit']}):undefined;
+  const output=await withValidationPhase({root:values.root,purpose:'technical-design',slice_id:values.slice,work_unit_id:values['work-unit'],readOnly:values['read-only']},async()=>{
+  const execution=values['approved-slice']?createApprovedExecutionContext({ref:values['approved-slice'],digest:values['approved-slice-digest'],approval_ref:values['approved-slice-approval']},{root:values.root,work_unit_id:values['work-unit'],readOnly:values['read-only']}):undefined;
   const result = await validateTechnicalDesign(read(path.resolve(positionals[0])), { root: values.root, sliceRef: values.slice, legacyDdd: values['legacy-ddd'], readOnly:values['read-only'], execution });
-  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return values['validation-dependencies']?{...result,validation_dependencies:validationDependencies()}:result;
+  });
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main().catch(error => { process.stderr.write(`${JSON.stringify({ result: 'blocked', errors: [error.message] })}\n`); process.exitCode = 1; });

package/template/.pi/skills/yss-ui-business-page-generation/SKILL.md

@@ -18,7 +18,9 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 - 只写文档、提交信息或发版流程，不生成业务页面代码。
 - 用户明确要求不用 YSS UI 组件库。
 
-## 必读参考
+## 按影响读取参考
+
+先读组件来源与当前实现合同；仅加载当前页面实际使用的组件、Hook、Utils 与交付验证资料，不预读所有专项技能。
 
 - 组件来源速查：`./references/component-map.md`
 - Hooks 速查：`./references/hooks-map.md`
@@ -56,7 +58,7 @@ description: "生成或改造完整 YSS UI CRUD、列表、表单、详情或左
 - 新增/导入/批量操作等主操作直接放入 `#toolbar-right` 插槽；**无需配置 `:toolbar-config="{ custom: true }"`**，避免无端展示列设置图标；**仅在业务明确需要列设置时才传入 `:toolbar-config="{ custom: true }"`**。
 - 删除确认默认使用 `YTable actionConfig.buttons[].isConfirm` 按钮项或 AntDV `Popconfirm` 气泡确认，禁止默认使用居中 `Modal.confirm`。
 - 样式抽离到 `style.less`，在 SFC 中使用 `<style scoped lang="less">@import './style.less';</style>`。
-- `index.vue` 原则上不超过 150 行；状态、API、副作用和处理方法进入 `hooks/`，列定义和静态配置进入 `constant.ts`。
+- `index.vue` 按职责保持可读；状态或副作用使视图难以理解时拆分，不以固定行数作为验收门禁；状态、API、副作用和处理方法进入 `hooks/`，列定义和静态配置进入 `constant.ts`。
 - 页面目录默认使用 `index.vue + constant.ts + style.less + hooks/`；只有存在多个私有视图或大量独立类型时才增加 `components/` 和 `type.ts`。`index.vue` 只做 Hook 组合、视图编排和事件转发。
 - 列表查询只维护一份 `currentParams`；查询、重置、树节点切换均回到第一页，翻页保留筛选条件，批量操作成功后清空选中态。组件 API 服从 `ytable-usage` / `ytree-usage`，请求和竞态服从 `yss-hook`。
 - Modal/Drawer 表单的 `open/mode/currentId/formModel/submitting`、回填、提交和关闭收敛在同一业务 Hook。新增/编辑数据在打开容器前准备，容器关闭时销毁并清理；默认依赖响应式 `mode`/model，不用动态 `:key` 强制重挂载。
@@ -84,7 +86,7 @@ src/views/{module-name}/
 
 ## 生成流程
 
-1. 读取本 skill 的三个 reference，并按上述文档检索顺序核对真实 API 与导出，禁止根据旧示例猜测。
+1. 读取组件来源速查；页面使用 Hook 或 Utils 时才追加相应 reference。按上述文档检索顺序核对真实 API 与导出，禁止根据旧示例猜测。
 2. 读取 `theme-token-usage`，检查项目真实主题变量与运行时同步链路。
 3. 若有截图或旧项目路径，先读取已批准且 digest 当前的 Visual Baseline manifest 和 `frontend_implementation_plan`，按 `case_id` 提取布局、状态、交互、响应式与控件类型验收项；缺失或摘要漂移时返回 `blocked`，不得凭目录或截图猜测。
 4. 按需求类型加载细分 skill：列表读 `ytable-usage` 与 `yss-hook`；表单读 `yss-formily`；编辑表格读 `yedit-table-usage`；树读 `ytree-usage`；导出下载读 `file-export-download`。

package/template/.pi/skills/yss-validation/SKILL.md

@@ -20,7 +20,7 @@ Read `references/source-index.md` as a path-hint index whenever the task depends
 ## Workflow
 
 1. Identify whether the task is JSR-303 annotation validation or an expression/EL parser request.
-2. Read `references/source-index.md`; for JSR-303 behavior, read `yss-component-validation-jsr303/readme.md` first.
+2. Select the approved platform index and inspect the actual POM, validation message resources, consuming Controller annotations and matching exception Advice. The current module README is empty; do not treat reading it as prerequisite evidence.
 3. 当前组件仓不存在历史 `yss-component-validation-engine-parent`；表达式、LiteFlow EL 或 `ExpressParserFactory` 请求返回 `blocked`，先确认真实组件来源和生命周期影响，不以旧索引或通用知识生成实现。
 4. Keep validation failures mapped to the service/API error contract used by the local project.
 5. 消费工程基线选择 javax/jakarta，不自行升级 Java/Boot。MVC 输入校验放在 server/client，业务不变量由 service/core 验证；不生成 DDD Domain。HTTP 失败形态由 server 的合同测试验证。

package/template/.pi/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/.pi/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/AGENTS.md

@@ -42,6 +42,8 @@
 
 ## 6. Ticket 与状态
 
+- Plan / Spec / Design 按 `docs/process/stage-tracking.md` 从阶段入口登记工作、按需拆分并在恢复 / 流转时验证；工作项进度不替代 Ticket 五态和阶段批准。
+
 - 每个功能先建父 Ticket，汇总阶段资产、审查、阻塞和证据。
 - Spec、设计、原型、OpenAPI Draft 和待冻结资产使用 `ready-for-human`；只有门禁通过、阻塞清除且可直接实现的垂直切片才能使用 `ready-for-agent`。
 - 按 `docs/agents/issue-tracker.md` 持久化主 tracker，不从 Git remote 推断；平台不可用时生成待发布草案。五态见 `docs/agents/triage-labels.md`。

package/template/CONTEXT.md

@@ -39,8 +39,9 @@ context_schema_version: 1
 | 技能投影 | 从权威共享技能生成、供特定 Agent root 加载的同步副本。 | — | 投影不是独立维护的技能源，不应在各 Agent root 中分别修改。 |
 | Spec | 记录用户问题、解决方案、用户故事、关键决策、验收标准和测试 seam 的产品研发规格。 | — | 新资产统一使用 Spec；旧规格称谓只在迁移记录中保留。 |
 | Spec Delta | 记录相对于既有冻结 Spec 基线的 `ADDED / MODIFIED / REMOVED` 行为、验收场景和测试映射。 | — | 不用于全新产品或全新模块，也不替代完整 Spec、OpenAPI 或架构资产。 |
+| 阶段工作项 | Plan、Spec、Design 中有明确负责人、验收和证据的工作记录；当前进度由 checkpoint.stage_tracking 持有，按需独立落盘。 | — | 不等同于业务 Ticket 或可实现垂直切片，不授予 ready-for-agent。 |
 | Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | — | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
-| 功能父 Ticket | 汇总一个功能从 Spec 到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
+| 功能父 Ticket | 汇总一个功能从 Plan 或最近可信接入阶段到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
 | 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | — | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
 | `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需会签（指定数字人或生物人）。 | — | 此状态不表示可以直接进入实现；也不等于某个数字人角色。 |
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | — | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |

package/template/README.md

@@ -102,6 +102,7 @@ scripts/verify-template-fast
 |------|------|
 | [AGENTS.md](./AGENTS.md) | 全局 AI 指令 + 工程基线入口 + Agent 协作 |
 | [docs/user-guide/用户手册.md](./docs/user-guide/用户手册.md) | 从首次只读检查到需求、开发、审查、发布和 CLI 操作的统一用户手册 |
+| [阶段接入与产物复用使用手册](./docs/user-guide/阶段接入与产物复用使用手册.md) | 复用上游资产，从指定入口继续；含后端交付后前端开发操作 |
 | [docs/process/PDCA-SCRUM.md](./docs/process/PDCA-SCRUM.md) | PDCA × Scrum × AI |
 | [docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md](./docs/process/MATT-POCOCK-ENGINEERING-SKILLS.md) | Matt Pocock Engineering Skills 集成与使用 |
 | [docs/process/lifecycle-registry.yaml](./docs/process/lifecycle-registry.yaml) | 生命周期结构事实源：主阶段、门禁、产物、工作单元、证据与稳定 ID |

package/template/docs/agents/issue-tracker.md

@@ -1,5 +1,6 @@
 ---
 tracker:
+  lifecycle_tracking_version: 1
   platform: local-markdown
   root: docs/.scratch
   legacy_roots:
@@ -135,3 +136,9 @@ Ticket 是默认 triage surface。MR / PR 是否纳入 triage 取决于当前平
 - Local Markdown：读取引用的 `docs/.scratch/<feature>/...` 文件；旧路径引用必须先经过迁移检查。
 - GitLab：使用 `glab issue view <iid> --comments`。
 - GitHub：使用 `gh issue view <number> --comments`。
+
+## 阶段工作追踪
+
+新初始化默认启用 `tracker.lifecycle_tracking_version: 1`。已有项目的 attach / sync 保留原配置；缺省保持旧模式，按 [阶段工作追踪](../process/stage-tracking.md) 执行 check → plan → apply。
+
+Plan / Spec / Design 的小工作记录在 checkpoint.stage_tracking；独立工作项使用 `work-items/<id>.md`，不占用业务票 / 实现切片的 `issues/`。执行进度只由 checkpoint 保存，父票和 map 引用；阶段工作项不得设置 `ready-for-agent`。

package/template/docs/process/contract-reading.md

@@ -0,0 +1,46 @@
+# 合同阅读、准备与显式迁移
+
+本文件描述工具入口；阶段、批准和执行门禁仍由 `docs/process/lifecycle-registry.yaml` 及资产所有者定义。YAML 是权威文件，视图不能编辑、批准合同或授予执行权限。
+
+```sh
+scripts/contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json]
+scripts/contract diff <旧资产> <新资产> --kind <类型> [--json]
+```
+
+默认 `review` 展示目标、非目标、验收、取舍、风险及未决事项，隐藏机器摘要明细，不附带折叠完整 JSON。`task` 保留适用工作单元、执行目录、写边界、Skill、验证、证据和未分类约束；Slice 必须明确 `--unit`。`full` 读取完整权威内容与绑定。三种视图均显示权威身份、版本、完整 SHA-256 和检查范围。批准有效性未核验；执行仍使用原预检和派发入口。来源未提供风险或取舍时明确标记缺口，不推断为无风险。
+
+| 类型 | 资产组 | 阅读后的权威处理入口 |
+|---|---|---|
+| `plan`、`spec` | Plan、Spec 范围、用户决定 | 生命周期和用户决定校验 |
+| `product-design`、`prototype-confirmation`、`visual-baseline` | 产品设计、确认、视觉基线 | 产品设计所有者校验 |
+| `technical-design` | 技术设计 | 技术设计校验与生命周期批准 |
+| `api-decision`、`data-decision` | API / 数据决定 | 对应决定校验、工程契约批准 |
+| `scaffold`、`scaffold-decision` | 脚手架合同、架构选择 | 脚手架所有者及原始用户决定 |
+| `slice` | Slice 与工作单元 | `scripts/slice-contract inspect`、原批准与派发 |
+| `handoff`、`backend-delivery`、`frontend-acceptance` | 战略交接、后端交付、前端接收 | 对应包 / 交付 / 接收验证器 |
+| `approval`、`user-decision`、`context-reconciliation` | 会签、原始回复、Context 对账 | 原批准 / 用户决定 / Context 校验 |
+
+通用适配器保留未知字段，只做可读取、适用 schema 和可识别来源绑定核对；不支持结构核验的类型会明确标记。专用资产所有者的业务校验并未被通用视图替代。Markdown 正文完整保留。API v2 审查结果从绑定的实际记录展示。摘要字段变化、数组顺序和纯字节变化均在 diff 中保留，不据此自动认定批准可沿用。
+
+## 准备机器字段
+
+Slice 继续使用 `scripts/slice-contract prepare`。来源的原始字节摘要、版本、别名、Skill 闭包和验证映射由现有准备器生成。共用的 `scripts/lib/contract-source.mjs` 只读取明确选择的来源；冲突报告保留 supplied / observed 和恢复动作，不根据目录猜测授权。其他资产继续使用各自的生成器，不新增项目人员要维护的表单。
+
+API 决定的新结构使用独立 v2 schema，v1 schema 和读取兼容保留：
+
+```sh
+scripts/api-contract-decision prepare <来源选择.yaml> --output <新草案.yaml>
+scripts/api-contract-decision migrate <已批准v1.yaml> --version v2 --output <新候选.yaml>
+```
+
+准备输入包括决定 ID / 版本、影响、评估引用、证据和业务原因；有 API 影响时再给 `openapi.id/ref/version`、`validation_record.ref`、`draft_review.ref` 和 `freeze.version/frozen_at`。摘要自动生成；来源明确但缺失时报告缺口。准备器不能产生批准状态。新路径以排他方式写入；已存在路径不能覆盖。
+
+v2 的 `openapi` 是唯一 Draft 绑定，`draft_review` 只存 `ref/digest`，Freeze 只保存版本和时间；实际结果、阻断项与 Draft 来源从真实审查记录读取。v1/v2 在消费时归一，外部永远绑定原文件 SHA-256。迁移先验证完整 v1，旧审查额外证据合并到顶层，旧文件与旧批准保持原字节。新候选按既有差异及授权延续协议处理，不继承批准。
+
+## 验证阶段与回退
+
+预检、准备、派发各自建立私有验证阶段。阶段绑定根目录、用途、切片、工作单元、只读状态；只在本次操作内共享输入和纯校验结果。原始输入不可变，返回给调用者的是独立副本。相同 schema、输入和格式选项复用；外部 `$ref` 未追踪的校验不享受结果复用。Python 引擎、同步 API 和技术设计 Node 边界保留。
+
+成功返回前复核所有登记原字节、目录枚举及不存在项。技术设计子进程自行验证批准，再返回依赖清单；父进程合并读取集合，读取矛盾、遗漏报告或异常均阻断。此清单不是批准上下文。品牌上下文不能序列化、跨仓或从只读升级；在阶段中生成的上下文结束后失效。调用者可传入 `AbortSignal`，已收到的撤回事件须中止当前操作；下一次边界始终重新读取当前批准和回复。未接入读取追踪的消费者保留原检查，不共享结果。
+
+P1 可回用原 `slice-contract` 阅读入口；P2 可回退阶段调用与本次改动的读取适配，恢复完整重复检查；P3 可停止创建 v2，但已生成 v2 的读取能力必须保留。回退后重新验证当前来源和批准，不恢复历史通过状态。

package/template/docs/process/lifecycle-artifact-map.md

@@ -14,7 +14,7 @@
 | `stage.spec-architecture` | Spec / 功能架构 | 固化解决方案和功能边界。 | Spec 基线和功能边界可审查。 |
 | `stage.product-design` | 产品设计 | 在存在产品设计影响时校准页面流和状态。 | 命中的设计门禁通过；未命中项记录 not-applicable 及原因。 |
 | `stage.system-data-engineering` | 系统 / 数据架构与工程契约 | 固化系统、数据、工程基线和 API 契约。 | 新建后端已由用户确认 DDD / MVC 与精确 Spring Boot 版本，既有工程已核验并复用登记值；受影响工程契约冻结或记录无 API 影响；required 脚手架证据齐全。 |
-| `stage.ticket-formalization` | Ticket 正式化 | 将冻结范围拆为可追踪的父 Ticket 和垂直切片。 | 工作单元窄、依赖清晰、验收和测试 seam 可执行。 |
+| `stage.ticket-formalization` | Ticket 正式化 | 在既有功能追踪入口下，将冻结范围正式化为垂直切片。 | 工作单元窄、依赖清晰、验收和测试 seam 可执行。 |
 | `stage.vertical-slice-implementation` | 垂直切片实现 | 以批准合同驱动 TDD 实现和跨仓库协作。 | 允许写路径、禁止模式、证据和验证命令全部满足。 |
 | `stage.verification-release-retrospective` | 验证 / 发布 / 复盘 | 完成 fresh verification、发布和回顾。 | 所有命中门禁通过，人工审查点已完成，checkpoint 可追溯。 |
 
@@ -82,7 +82,7 @@
 | `artifact.implementation-repository-preparation-result` | 实现仓库准备结果 | `stage.system-data-engineering` | 后端或前端交付面进入 Ticket 正式化。 |
 | `artifact.tactical-design` | DDD 战术设计 | `stage.system-data-engineering` | 聚合边界、状态机、一致性或持久化映射复杂到无法在系统概要设计的 Tactical DDD Check 中清楚表达。 |
 | `artifact.spec-delta` | Spec Delta | `stage.spec-architecture` | 已有冻结 Spec 的高风险行为变化。 |
-| `artifact.parent-ticket` | 功能父 Ticket | `stage.ticket-formalization` | 每个进入追踪的功能。 |
+| `artifact.parent-ticket` | 功能父 Ticket | `stage.plan` | 每个功能首次进入 Plan 或最近可信接入阶段时建立，正式化时复用；Design profile 不创建工程父 Ticket。 |
 | `artifact.vertical-slice-ticket` | 垂直切片 Ticket | `stage.ticket-formalization` | 进入实现前。 |
 | `artifact.slice-implementation-contract` | Slice Implementation Contract | `stage.ticket-formalization` | Agent 进入实现。 |
 | `artifact.frontend-implementation-plan` | 前端实现还原计划 | `stage.ticket-formalization` | UI 影响切片提升 ready-for-agent 前。 |

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "38afc53efe827596c036133c826acd818c8dab85fab0f430d62a60cf62005196",
+  "semantic_sha256": "09490c2a354d5452d52522cc36e04cec044faf62cb3c80c90bf95cd07963f0fb",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
@@ -104,6 +104,7 @@
     "stage.verification-release-retrospective",
     "stage.vertical-slice-implementation",
     "work-unit.attach-sync-integration",
+    "work-unit.backend-delivery",
     "work-unit.code-review",
     "work-unit.discovery-opportunity",
     "work-unit.discovery-requirements",

package/template/docs/process/lifecycle-registry.yaml

@@ -62,7 +62,7 @@ stages:
     exit_criteria: 新建后端已由用户确认 DDD / MVC 与精确 Spring Boot 版本，既有工程已核验并复用登记值；受影响工程契约冻结或记录无 API 影响；required 脚手架证据齐全。
   - id: stage.ticket-formalization
     name: Ticket 正式化
-    goal: 将冻结范围拆为可追踪的父 Ticket 和垂直切片。
+    goal: 在既有功能追踪入口下，将冻结范围正式化为垂直切片。
     exit_criteria: 工作单元窄、依赖清晰、验收和测试 seam 可执行。
   - id: stage.vertical-slice-implementation
     name: 垂直切片实现
@@ -309,8 +309,8 @@ artifacts:
     trigger: 已有冻结 Spec 的高风险行为变化。
   - id: artifact.parent-ticket
     name: 功能父 Ticket
-    stage: stage.ticket-formalization
-    trigger: 每个进入追踪的功能。
+    stage: stage.plan
+    trigger: 每个功能首次进入 Plan 或最近可信接入阶段时建立，正式化时复用；Design profile 不创建工程父 Ticket。
   - id: artifact.vertical-slice-ticket
     name: 垂直切片 Ticket
     stage: stage.ticket-formalization
@@ -445,7 +445,7 @@ work_units:
     name: 垂直切片 Ticket 正式化
     scope: project-instance
     input: 冻结 Spec、设计、契约和阻塞关系。
-    output: 功能父 Ticket、垂直切片和批准的 Slice Implementation Contract。
+    output: 更新既有功能父 Ticket 的关联、形成垂直切片和批准的 Slice Implementation Contract。
     completion: 切片可独立验证；生命周期复算后才能 ready-for-agent。
   - id: work-unit.slice-implementation
     name: 垂直切片实现
@@ -465,6 +465,12 @@ work_units:
     input: 不可变候选快照、Spec、Ticket、合同和执行结果。
     output: Standards、Spec、UI fidelity 三轴 Review 与 fresh verification。
     completion: findings 已处理；修复后重新捕获候选并全量复审。
+  - id: work-unit.backend-delivery
+    name: 后端职责交付终点
+    scope: project-instance
+    input: plan-to-backend 职责范围、当前 Slice 批准与独立代码审查、Backend Delivery 源文件及正式导出包。
+    output: 绑定当前源、独立审查和正式包的后端终点记录及下游前端待办。
+    completion: 完整复验源文件与正式包；仅后端可交付，不能宣布全业务完成或自动发布。
   - id: work-unit.release-and-retrospective
     name: 发布与复盘
     scope: project-instance