create-yss-spec 3.5.3 → 3.5.5

package/template/.template-spec/templates/examples/plan-spec/ordinary-valid.md

@@ -0,0 +1,36 @@
+---
+content_profile: plan-spec-v1
+---
+
+# 附件提交校验
+
+> 虚构输入；仅为确定性 fixture，不代表已批准业务。
+
+## 功能需求
+
+| ID | 需求 | 优先级 | 来源引用 | 验收引用 | 未决项 |
+|---|---|---|---|---|---|
+| FR-001 | 点击提交时检查本单据必需附件，缺少任一项时拒绝且保持草稿 | P0 | .template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S1；.template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S2 | AC-001 | 无 |
+| FR-002 | 一次列出全部缺失附件名称，并保留当前页面已填数据 | P0 | .template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S3；.template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S4 | AC-001 | 无 |
+| FR-003 | 补齐后重新提交并重新校验，齐全且其他条件满足时沿既有流程 | P0 | .template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S5；.template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S6 | AC-002 | 无 |
+
+## 非功能需求
+
+not-applicable：本样本未新增独立非功能目标。
+
+## 验收标准
+
+| ID | 需求引用 | 前提 | 触发 | 可观察结果 | 场景类型 | 未决项 |
+|---|---|---|---|---|---|---|
+| AC-001 | FR-001, FR-002 | 草稿缺少两项必需附件且页面有已填数据 | 点击提交 | 拒绝提交；保持草稿；同时列出两项名称并保留当前页面数据 | 拒绝 / 边界 | 无 |
+| AC-002 | FR-003 | 已补齐全部必需附件且其他提交条件满足 | 再次点击提交 | 重新检查并沿既有流程提交 | 恢复 / 成功 | 无 |
+
+## 未决项
+
+| ID | 问题 | 判断依据 | 责任人 | 解决时点 | 接收方 / 解决证据 |
+|---|---|---|---|---|---|
+| Q-001 | 读取附件清单失败时的行为待确认；安排需求澄清 | .template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S8；关键行为未知，不延期越过冻结 | 产品负责人（虚构角色） | Spec 冻结前 | Spec 起草者 / 待取得真实决定 |
+
+## 非目标范围
+
+不校验附件真实性；不承诺刷新或关闭后的恢复。来源：.template-spec/templates/examples/plan-spec/ordinary-source.md :: id:S7。读取清单失败时行为仍未知，验收例子不确定它。

package/template/.template-spec/templates/local-parent-ticket-template.md

@@ -26,14 +26,18 @@ Status: ready-for-human
 | publication | local / pending |
 | pending_publication_to | none / github / gitlab |
 
-## 生命周期状态
+## 生命周期查询
 
-| 字段 | 值 |
-|---|---|
-| stage | `<current-stage>` |
-| lifecycle_status | routing / running / paused-human-gate / blocked / completed |
-| ticket_role | needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix |
-| gate_summary | `<approved / blocked / not-applicable summary>` |
+Checkpoint：`docs/.scratch/<feature>/checkpoint.yaml`（填写实际存在的路径）。
+
+阶段、阻塞、门禁摘要与下一工作单元从同一 checkpoint 按需查询；本票只保存 Ticket 五态、业务说明与资产入口。
+
+```sh
+scripts/lifecycle-status --root . --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+scripts/stage-tracking check --root . --checkpoint docs/.scratch/<feature>/checkpoint.yaml
+```
+
+查询不写文件，也不授予执行权限。批准依据仍读取下方会签记录。
 
 ## 资产与证据
 
@@ -50,16 +54,20 @@ Status: ready-for-human
 
 会签记录写在 `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml`。会签桶内门禁标为 `approved` 前必须通过 `scripts/verify-approval-record`。
 
-| 门禁 | 记录路径 | 会签角色 | 状态 |
-|---|---|---|---|
-|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `.template-spec/agents/digital-human-roles.yaml` | pending / approved / blocked / not-applicable |
+| 门禁 | 记录路径 | 会签角色 |
+|---|---|---|
+|  | `docs/.scratch/<feature>/gates/<gate-id>-approval.yaml` | 见 `.template-spec/agents/digital-human-roles.yaml` |
 
-## 阻塞关系
+会签结果读取记录原件；阻塞关系与下一工作单元读取上述 checkpoint，不在本票重填状态表。
 
-- 无 / 被 `<ticket-path>` 阻塞
+## Comments
 
-## 下一工作单元
+## 拆分与就绪
 
-`<next-work-unit>`
+| 维度 | 资产与证据入口 |
+|---|---|
+| 业务拆分 | <business-ticket-set.yaml / 业务正式化记录> |
+| 实现拆分 | <issues/ 与 Ticket 正式化记录> |
+| 实现就绪 | <当前合同批准、仓库准备与就绪检查引用> |
 
-## Comments
+如声明业务集合已同步，在 frontmatter 增加 business_ticket_set_ref 与 business_ticket_set_digest（当前集合原字节），不复制票据正文。

package/template/.template-spec/templates/spec-delta-template.md

@@ -16,11 +16,13 @@
 
 ## 2. 行为差异
 
-| 类型 | 行为 | 当前状态 | 目标状态 | 影响范围 |
-|---|---|---|---|---|
-| ADDED |  |  |  |  |
-| MODIFIED |  |  |  |  |
-| REMOVED |  |  |  |  |
+| 类型 | 行为 | 当前状态 | 目标状态 | 影响范围 | 关联 FR/NFR/AC |
+|---|---|---|---|---|---|
+| ADDED |  |  |  |  |  |
+| MODIFIED |  |  |  |  |  |
+| REMOVED |  |  |  |  |  |
+
+关联使用稳定 ID 并注明旧 / 新基线文件；删除项保留旧 ID，不复用。可附 `inspect-plan-spec diff` 的诊断和原始字节差异，缺少旧基线时明确“无法比较”。该辅助证据不判定语义等价、不延续批准、不缩小验证范围。
 
 说明：
 

package/template/.template-spec/templates/spec-template.md

@@ -1,4 +1,5 @@
 ---
+content_profile: plan-spec-v1
 pipeline: <feature-id>
 stage: open
 status: ready-for-human
@@ -9,6 +10,10 @@ owner: ai
 
 填写前读取[中文写作规范](../process/document-writing.md)和 [Spec 对照](examples/lifecycle-writing-examples.md#2-spec让规则可以转成验收)。保留原规则、例外和不确定性；输入缺失时记录待确认项。
 
+## 业务 Ticket 草案
+
+集合：`docs/.scratch/<feature>/business-ticket-set.yaml`。Spec 综合同时起草，Design 校准同一组 ID；集合只存引用及覆盖处置，正文按业务 Ticket 模板填写。此处只引用路径，避免 Spec 与集合摘要循环。
+
 ## 功能父 Ticket
 
 <Local：`docs/.scratch/<feature>/parent-ticket.md`；GitHub / GitLab：Issue URL / 编号>
@@ -29,28 +34,29 @@ owner: ai
 
 需求写明主体、触发条件和可观察结果；关联验收标准。不要用“完善、友好、高效”代替规则。
 
-| ID | 需求 | 优先级 | 备注 |
-|---|---|---|---|
-| FR-001 | | P0/P1/P2 | |
+| ID | 需求 | 优先级 | 来源引用 | 验收引用 | 未决项 |
+|---|---|---|---|---|---|
+| FR-001 | <主体、触发、结果及例外> | P0/P1/P2 | <项目根相对路径> :: id:<已有条目ID> | AC-001 / 待补 Q-001 | 无 / Q-001 |
 
 ## 非功能需求
 
 命中时填写工作负载或适用条件、目标值及单位、验证方式与依据；尚未确认的目标保留为未决项，不补造性能承诺。
 
-| 类别 | 需求 | 目标 |
-|---|---|---|
-| 性能 | | |
-| 可靠性 | | |
+没有适用非功能约束时写 `not-applicable：<原因>`，不保留空行。验证方法允许测试、检查、分析、演示，不强迫定性约束数值化。
+
+| ID | 需求 | 适用条件/负载 | 指标及单位 | 目标 | 确认状态 | 验证方法 | 来源引用 | 验收引用 | 未决项 |
+|---|---|---|---|---|---|---|---|---|---|
+| NFR-001 | <填写> | <填写> | <量化口径或定性判断依据> | <填写或未知> | 候选 / 已确认 | <填写> | <项目根相对路径> :: heading:<准确章节名> | AC-002 / 待补 Q-001 | 无 / Q-001 |
 
 ## 验收标准
 
 关联需求 ID，按实际影响覆盖成功、拒绝、边界和恢复。保留“全部”“仅当”等限定；测试数据不能反向扩展业务规则。
 
-```gherkin
-假如 <上下文>
-当 <操作>
-那么 <可观察结果>
-```
+| ID | 需求引用 | 前提 | 触发 | 可观察结果 | 场景类型 | 未决项 |
+|---|---|---|---|---|---|---|
+| AC-001 | FR-001 | <填写> | <填写> | <填写或待确认 Q-001> | 成功 / 拒绝 / 边界 / 状态变化 / 恢复 | 无 / Q-001 |
+
+可在表后补充 Gherkin 示例；正式 ID 在表中登记。FR/NFR/AC 在同一功能内稳定，重排不重新编号，删除后不复用。来源使用项目根相对路径及已有 ID；无 ID 时引用准确章节名，不伪造锚点。详见 [表达约定与诊断](../process/plan-spec-quality.md)。
 
 ## 产品总体设计 / 功能架构
 
@@ -100,11 +106,13 @@ owner: ai
 
 ## AI / 人工审查点
 
+以下三行仅为示例，起草时替换为实际影响面；审查与会签以既有角色政策为准，示例不会新增门禁。
+
 | 范围 | Agent 权限 | 是否需要人工审查 | 备注 |
 |---|---|---|---|
-| 支付逻辑 | 记录验证证据 | 是 | |
-| 原生 SQL | 记录验证证据 | 是 | |
-| 公共基础库 API | 记录验证证据 | 是 | |
+| 示例：支付逻辑 | 记录验证证据 | 是 | |
+| 示例：原生 SQL | 记录验证证据 | 是 | |
+| 示例：公共基础库 API | 记录验证证据 | 是 | |
 
 ## 非目标范围
 
@@ -113,3 +121,11 @@ owner: ai
 ## 风险
 
 记录已知风险和未决项的影响、责任人、解决时点及接收方；尚未明确原因时保留现象和验证方法。
+
+## 未决项
+
+| ID | 问题 | 判断依据 | 责任人 | 解决时点 | 接收方 / 解决证据 |
+|---|---|---|---|---|---|
+| Q-001 | <未知事项及补齐动作> | <影响与延期理由> | <负责人> | <解决时点> | <接收方> |
+
+未决项不会因验收示例而转成已确认行为；适用条件不命中时保留原因。`content_profile` 可选，仅声明创作格式，不代表生命周期 schema 或批准状态。

package/template/.template-spec/templates/vertical-slice-ticket-template.md

@@ -1,5 +1,9 @@
 ---
+kind: vertical-slice-ticket
 status: ready-for-human
+business_ticket_set_ref: docs/.scratch/<feature>/business-ticket-set.yaml
+business_ticket_refs: [BT-001]
+acceptance_refs: [AC-001]
 requirement_version: v1
 ---
 

package/template/AGENTS.md

@@ -37,7 +37,7 @@
 - 先按 `.template-spec/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `.template-spec/process/lifecycle-registry.yaml`；阅读导航见 `.template-spec/process/lifecycle-artifact-map.md`。
 - 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
 - 新功能和较大变更先进入 Plan；`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
-- Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
+- Spec 综合同时起草业务 Ticket 集，Design 校准同一组 ID；业务正式化后战略交接或技术分析，协议见 `.template-spec/process/business-tickets.md`。业务票不授予实现资格。Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
 - `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 
 ## 6. Ticket 与状态

package/template/CONTEXT.md

@@ -46,6 +46,7 @@ context_schema_version: 1
 | 阶段工作项 | Plan、Spec、Design 中有明确负责人、验收和证据的工作记录；当前进度由 checkpoint.stage_tracking 持有，按需独立落盘。 | — | 不等同于业务 Ticket 或可实现垂直切片，不授予 ready-for-agent。 |
 | Ticket | 在追踪平台上承载功能生命周期或可实现工作单元的通用追踪对象。 | — | GitHub Issues / GitLab Issues 是具体平台对象名称；领域资产统一称为 Ticket。 |
 | 功能父 Ticket | 汇总一个功能从 Plan 或最近可信接入阶段到契约冻结的阶段状态、资产链接、审查结论和阻塞项的 Ticket。 | — | 不作为 Agent 直接实现的垂直切片。 |
+| 业务 Ticket | Spec 起草、Design 校准的用户行为和可验收结果；集合保存引用、覆盖和依赖。 | — | 不依赖实现工程，不授予 ready-for-agent；可由研发细化为多个实现 Slice。 |
 | 垂直切片 Ticket | 契约冻结后生成的可独立验证实现单元，记录范围、阻塞关系、验收标准和验证证据。 | — | 只有通过必要门禁并具备直接实现条件时才能标记 `ready-for-agent`。 |
 | `ready-for-human` | 表示 Spec、设计、契约草案或其他资产仍需会签（指定数字人或生物人）。 | — | 此状态不表示可以直接进入实现；也不等于某个数字人角色。 |
 | `ready-for-agent` | 表示垂直切片已通过必要门禁并具备直接实现条件的流程状态。 | — | 不得用于 Spec 初稿、原型、OpenAPI Draft 或其他未冻结资产。 |

package/template/DESIGN.md

@@ -77,6 +77,23 @@ spacing:
   xxl: 48px
 
 components:
+  workspace-header:
+    height: 48px
+    backgroundColor: "{colors.surface}"
+    typography: "{typography.body}"
+  workspace-sidebar:
+    width: 240px
+    backgroundColor: "{colors.surface}"
+  workspace-sidebar-collapsed:
+    width: 64px
+  workspace-tabs:
+    height: 32px
+    backgroundColor: "{colors.surface}"
+  workspace-detail:
+    width: 384px
+    backgroundColor: "{colors.surface}"
+  workspace-title:
+    typography: "{typography.heading-md}"
   separator:
     backgroundColor: "{colors.border}"
     height: 1px
@@ -226,7 +243,7 @@ components:
 
 YSS is an enterprise UI system for dense, scannable work surfaces: tables, forms, filters, workflows and operational feedback. This file is the normative source for visual tokens and component visual variants. Product behavior remains in Spec, interaction specifications and state matrices.
 
-The default theme adopts Data Quality global tokens on the Ant Design v6 design foundation: light mode, primary #3371ff, body 14px, controls 32/24/40px, radii 6/4/8px and card padding 20px. Compact and dark modes are opt-in. Data Quality runs Vue 3 + Ant Design Vue 4.2.6 + YSS UI; that runtime version is distinct from the design foundation. Client-specific JSP themes and page-local glass effects are not defaults. Prototypes use HTML/CSS/JavaScript with local token CSS. Production applications use the target implementation contract and lockfile; prototype visuals do not establish production component API compatibility.
+The production default theme adopts Data Quality global tokens on the Ant Design v6 design foundation: light mode, primary #3371ff, body 14px, controls 32/24/40px, radii 6/4/8px and card padding 20px. Production compact remains opt-in. New high-fidelity prototypes default to light compact using the named variants below; comfortable remains available. Existing page changes preserve their approved density and layout. Dark assets are historical references, unverified against the current specification, and are outside the default prototype route. Data Quality runs Vue 3 + Ant Design Vue 4.2.6 + YSS UI; that runtime version is distinct from the design foundation. Client-specific JSP themes and page-local glass effects are not defaults. New high-fidelity prototypes primarily use prebuilt shadcn-vue + Vue 3 with local token CSS. React authoring libraries and generation routes are retired; sealed React evidence is read-only legacy. Native HTML/CSS/JavaScript remains the lightweight route. Use registered components for product controls and task-specific compositions; upstream Blocks do not override these tokens or approved behavior. Production applications use the target implementation contract and lockfile; prototype visuals do not establish production component API compatibility.
 
 ## Colors
 
@@ -238,7 +255,9 @@ Use the system font stack, 14px body text and 400/600 weights. Use `caption` onl
 
 ## Layout
 
-Use a 4px spacing grid and the spacing tokens above. Use the default 32px control variant directly in HTML prototypes. The explicit compact variant uses 28px; small and large controls use 24px and 40px. When production uses an Ant Design theme algorithm, keep its seed `controlHeight` at 32px and apply compact once; never seed 28px and compact again. Page, container and overlay surfaces form the base three-layer model. On narrow screens, toolbars and filters reflow or collapse; table overflow is restricted to the table container.
+New enterprise prototypes use an application shell with module navigation, grouped sidebar, closable page Tags and a full-width work area. Page Tags are navigation controls with a subtle primary tint and border for the current page, separate activation and close buttons, and no Tab underline. Reserve Tabs for views within a page; their active state uses primary text and an indicator without a filled pill. The existing workspace-tabs roles continue to size and color the Tag strip. Collapsed sidebar items remain centered with a visible current-page marker and inverse Tooltips; tooltip bodies and arrows share the same surface. Shell dimensions come from the workspace component roles above. At 1200px and above the sidebar starts expanded; from 768px to 1199px it starts collapsed; below 768px navigation uses a modal Sheet. A selected list detail occupies the workspace-detail role on wide desktop and a Sheet below 1200px; no empty detail column is reserved. Forms retain a bounded reading width within the fluid workspace. Use one main vertical work-area scroll, an independent detail scroll where needed and localized table overflow. Workspace page titles use workspace-title; avoid repeating a large decorative title above task controls. These are prototype defaults, not an automatic migration of approved or production pages.
+
+Use a 4px spacing grid and the spacing tokens above. New prototypes use the named compact control variant (28px) on desktop, the ordinary variant (32px) on narrow screens, and body typography (14px) throughout. Comfortable uses the ordinary control and card variants. Compact uses card-compact padding on desktop and spacing.sm on narrow screens. Small and large control variants remain 24px and 40px. These named prototype variants are not the full production tokens.compact.json algorithm result; do not apply a compact algorithm to them. When production uses an Ant Design theme algorithm, keep its seed `controlHeight` at 32px and apply compact once; never seed 28px and compact again. Page, container and overlay surfaces form the base three-layer model. On narrow screens, toolbars and filters reflow or collapse; table overflow is restricted to the table container.
 
 ## Elevation & Depth
 
@@ -250,12 +269,12 @@ Controls use `rounded.md` (6px); cards and overlays use `rounded.lg` (8px); comp
 
 ## Components
 
-The component keys above describe default visual variants and explicitly named optional sizes, not business states. Default controls use a 32px computed height, 14px body type, pale semantic feedback surfaces and visible focus rings. Required implementation states include hover, focus, active, disabled, loading, error, empty, readonly, no-permission, conflict and success. Define those behavior and acceptance details in the lifecycle state-matrix and prototype evidence assets.
+The component keys above describe default visual variants and explicitly named optional sizes, not business states. The ordinary control variant uses a 32px computed height; prototype density selects the named variant as described in Layout. All variants retain body typography, pale semantic feedback surfaces and visible focus rings. Validate actual target size and spacing, keyboard operation and focus; control height alone does not establish accessibility. Required implementation states include hover, focus, active, disabled, loading, error, empty, readonly, no-permission, conflict and success. Define those behavior and acceptance details in the lifecycle state-matrix and prototype evidence assets.
 
 ## Do's and Don'ts
 
 - Do consume tokens through ConfigProvider, CSS variables or the target component library theme.
-- Do use the verified derived dark/compact token snapshot for HTML; production theme algorithms remain implementation-specific.
+- Do use local CSS projected from this specification for prototypes; production theme algorithms remain implementation-specific. Dark snapshots are historical and require new derivation and validation before adoption.
 - Do verify desktop (`1440x900`), mobile (`390x844`) and impacted intermediate viewports.
 - Do provide visible feedback for save, submit, publish, export and retry actions.
 - Don’t use marketing hero layouts, large gradients or decorative cards in operational pages.

package/template/scripts/check-plan-stage-coverage

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import {parseArgs} from 'node:util';
+import {planStageCoverage} from './lib/plan-stage-coverage.mjs';
+try {
+ const {values}=parseArgs({options:{root:{type:'string'},plan:{type:'string'},decisions:{type:'string'},package:{type:'string'},mapping:{type:'string'},output:{type:'string'}}});
+ if(!values.plan||!values.decisions||!values.package)throw Error('需要 --plan <md> --decisions <md> --package <json|yaml> [--mapping <json>]');
+ const result=planStageCoverage(path.resolve(values.root||process.cwd()),{plan_ref:values.plan,decisions_ref:values.decisions,package_ref:values.package,mapping_ref:values.mapping});
+ const text=JSON.stringify(result,null,2)+'\n';if(values.output)fs.writeFileSync(values.output,text,{flag:'wx'});process.stdout.write(text);
+ if(result.coverage_status!=='complete')process.exitCode=1;
+}catch(error){process.stderr.write(JSON.stringify({status:'unassessed',error:error.message})+'\n');process.exitCode=1;}

package/template/scripts/contract

@@ -1,13 +1,31 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import {readFileSync,writeFileSync} from 'node:fs';
+import {safe} from './lib/strategic-handoff-io.mjs';
+import {renderReadingBundle,checkReadingViews,readingCheckpointsForAsset,saveReadingComparison,planEnableReading,applyEnableReading} from './lib/reading-view-bundle.mjs';
 import {viewContract,diffContract,prepareContractReview} from './lib/contract-views.mjs';
+import {isAssetCommand,runAssetCommand} from './lib/asset-command.mjs';
+if(isAssetCommand(process.argv[2])) {
+ try { process.stdout.write(JSON.stringify(runAssetCommand(process.argv.slice(2)),null,2)+'\n'); }
+ catch(error) { process.stderr.write(JSON.stringify({status:'blocked',error:error.message})+'\n');process.exitCode=1; }
+} else {
 try{
  const args=process.argv.slice(2),mode=args.shift(),options={},positional=[];
- for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root','decision','task-layout'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
- const config={kind:options.kind,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,task_layout:options['task-layout']||'legacy',beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined,decision_ref:options.decision};
+ for(let i=0;i<args.length;i++){const arg=args[i];if(arg==='--json')options.json=true;else if(arg==='--model')options.model=true;else if(arg.startsWith('--')){const key=arg.slice(2);if(!['kind','profile','unit','root','before-root','decision','task-layout','checkpoint','output'].includes(key)||!args[i+1]||args[i+1].startsWith('--'))throw Error(`未知或缺值参数 ${arg}`);options[key]=args[++i];}else positional.push(arg);}
+ const config={kind:options.kind,include_reading_model:options.model===true,root:path.resolve(options.root||process.cwd()),profile:options.profile||'review',unit_id:options.unit,task_layout:options['task-layout']||'legacy',beforeRoot:options['before-root']?path.resolve(options['before-root']):undefined,decision_ref:options.decision};
+ if(['render','check-views','plan-enable','apply-enable'].includes(mode)){
+  if(mode==='apply-enable'?positional.length!==1:!options.checkpoint||positional.length)throw Error('reading-command-arguments-invalid');
+  const result=mode==='render'?renderReadingBundle(config.root,options.checkpoint):mode==='check-views'?checkReadingViews(config.root,options.checkpoint):mode==='plan-enable'?planEnableReading(config.root,options.checkpoint):applyEnableReading(config.root,JSON.parse(readFileSync(safe(config.root,positional[0]),'utf8')));
+  if(mode==='plan-enable'&&options.output)writeFileSync(safe(config.root,options.output,{missing:true}),JSON.stringify(result,null,2)+'\n',{flag:'wx'});
+  process.stdout.write(JSON.stringify(result,null,2)+'\n');if(result.blockers?.length||result.reading_update?.status==='failed')process.exitCode=1;
+ }else{
  if(!options.kind)throw Error('必须用 --kind 明确资产类型');
  if(!['view','diff','prepare-review'].includes(mode)||positional.length!==(mode==='view'?1:2))throw Error('用法: contract view <资产> --kind <类型> [--profile review|task|full] [--unit <ID>] [--json] | diff|prepare-review <旧资产> <新资产> --kind <类型> [--decision <原决定>]');
+ if(mode==='prepare-review')for(const checkpoint of readingCheckpointsForAsset(config.root,positional[1],config.kind))renderReadingBundle(config.root,checkpoint);
  const result=mode==='view'?viewContract(positional[0],config):mode==='prepare-review'?prepareContractReview(positional[0],positional[1],config):diffContract(positional[0],positional[1],config);
+ if(mode==='prepare-review'&&options.checkpoint&&!result.blockers?.length)result.saved_comparison=saveReadingComparison(config.root,options.checkpoint,result);
  process.stdout.write(options.json||!result.markdown?JSON.stringify(result,null,2)+'\n':result.markdown);
  if(result.blockers?.length)process.exitCode=1;
+ }
 }catch(error){process.stderr.write(error.message+'\n');process.exitCode=1;}
+}

package/template/scripts/feature-assets

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { inspectAssets, planAssets, applyAssets, restoreAssets } from './lib/feature-assets.mjs';
+try {
+  const {values,positionals}=parseArgs({allowPositionals:true,strict:true,options:{root:{type:'string'},checkpoint:{type:'string'},candidate:{type:'string',multiple:true},'archive-dir':{type:'string'},plan:{type:'string'},receipt:{type:'string'},json:{type:'boolean'},help:{type:'boolean'}}});
+  if(values.help) process.stdout.write('feature-assets inspect|plan --root <project> --checkpoint <ref> [--candidate <ref> ... --archive-dir <external-dir>] [--json]\nfeature-assets apply --root <project> --plan <external-plan.json>\nfeature-assets restore --root <project> --receipt <external-receipt.json>\nplan writes JSON to stdout only; apply never grants lifecycle approval.\n');
+  else {
+    if(!values.root||positionals.length!==1)throw Error('explicit-root-and-command-required');
+    const root=path.resolve(values.root),command=positionals[0];let result;
+    if(command==='inspect') result=inspectAssets({root,checkpoint:values.checkpoint});
+    else if(command==='plan')result=planAssets({root,checkpoint:values.checkpoint,candidates:values.candidate,archiveDir:values['archive-dir']});
+    else if(command==='apply'){
+      const ref=fs.realpathSync(values.plan),realRoot=fs.realpathSync(root);
+      if(ref===realRoot||ref.startsWith(realRoot+path.sep))throw Error('plan-must-be-outside-project');
+      result=applyAssets({root,plan:JSON.parse(fs.readFileSync(ref,'utf8'))});
+    } else if(command==='restore')result=restoreAssets({root,receiptRef:values.receipt});
+    else throw Error('unknown-command');
+    process.stdout.write(JSON.stringify(result,null,2)+'\n');
+    if(result.status==='partial')process.exitCode=1;
+  }
+} catch(error) {process.stderr.write(error.message+'\n');process.exitCode=2;}

package/template/scripts/inspect-plan-spec

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { inspectPlanSpec, renderReport } from './lib/plan-spec-quality.mjs';
+const help = `只读 Plan / Spec 诊断（不改变阶段、批准或就绪状态）
+inspect-plan-spec check --root <项目根> [--plan <Plan>] [--spec <Spec>] [--slice <Slice YAML>] [--json]
+inspect-plan-spec diff --root <项目根> --before <旧Spec> --after <新Spec> [--json]
+check 至少指定 Plan、Spec 之一；--slice 可重复。路径相对项目根，来源不联网、不扫描。
+退出码 0：诊断执行完成（可有发现）；2：输入、解析或新鲜度不足。
+`;
+const argv = process.argv.slice(2);
+if (argv.includes('--help') || argv.includes('-h')) { process.stdout.write(help); }
+else {
+  const options = { command: argv.shift(), slices: [] };
+  try {
+    while (argv.length) {
+      const flag = argv.shift();
+      if (flag === '--json') { options.json = true; continue; }
+      if (!['--root', '--plan', '--spec', '--before', '--after', '--slice'].includes(flag)) throw new Error(`不支持参数 ${flag}`);
+      const value = argv.shift();
+      if (!value || value.startsWith('--')) throw new Error(`${flag} 缺少值`);
+      if (flag === '--slice') options.slices.push(value);
+      else { const key = flag.slice(2); if (options[key]) throw new Error(`${flag} 不允许重复`); options[key] = value; }
+    }
+    if (options.command === 'check' && (options.before || options.after) || options.command === 'diff' && (options.plan || options.spec || options.slices.length)) throw new Error('参数不适用于当前命令');
+    const { report, exitCode } = await inspectPlanSpec(options);
+    process.stdout.write(options.json ? `${JSON.stringify(report, null, 2)}\n` : renderReport(report));
+    process.exitCode = exitCode;
+  } catch (error) {
+    const message = { tool: 'inspect-plan-spec', tool_version: '1.0.0', diagnostic_only: true, execution: 'incomplete', findings: [{ code: 'INPUT_ARGUMENT', location: { file: '.', line: 1, column: 1 }, item_id: null, message: error.message, recovery: '查看 --help 并修正参数。' }] };
+    process.stdout.write(process.argv.includes('--json') ? `${JSON.stringify(message, null, 2)}\n` : `${error.message}\n${help}`);
+    process.exitCode = 2;
+  }
+}

package/template/scripts/inspect-skill-discovery

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { inspectSkill, observeRuntime, assessDiscovery } from './lib/skill-discovery.mjs';
+import { parseDocument } from './vendor/yaml.mjs';
+
+try {
+  const args = {};
+  for (let index = 2; index < process.argv.length; index += 2) {
+    const key = process.argv[index], value = process.argv[index + 1];
+    if (!['--runtime', '--binary', '--cwd', '--pi-loader', '--pi-agent-dir', '--selections', '--required'].includes(key) || !value || value.startsWith('--')) throw new Error(`invalid argument: ${key}`);
+    args[key.slice(2)] = value;
+  }
+  if (!['codex', 'pi', 'cursor'].includes(args.runtime) || !args.binary) throw new Error('--runtime codex|pi|cursor and --binary are required');
+  const cwd = path.resolve(args.cwd ?? '.');
+  const document = parseDocument(readFileSync(path.join(cwd, '.template-spec/agents/yss-skill-registry.yaml'), 'utf8'), { uniqueKeys: true, maxAliasCount: 0 });
+  if (document.errors.length) throw new Error('invalid registry');
+  const registry = document.toJS({ maxAliasCount: 0 });
+  const registered = registry.skills.map((item) => inspectSkill(path.join(cwd, '.agents/skills', item.id, 'SKILL.md')));
+  const observation = await observeRuntime({ runtime: args.runtime, binary: args.binary, cwd, piLoader: args['pi-loader'], piAgentDir: args['pi-agent-dir'] });
+  const assessment = assessDiscovery({ registered, observation, expected: { runtime: args.runtime, version: observation.version, cwd }, required: (args.required ?? '').split(',').filter(Boolean), selections: args.selections ? JSON.parse(readFileSync(args.selections, 'utf8')) : [] });
+  process.stdout.write(JSON.stringify({ schema_version: 1, registered, observation, assessment }, null, 2) + '\n');
+  if (assessment.status === 'blocked' || observation.status !== 'observed' || observation.errors?.some((item) => args.runtime === 'codex' || item.type === 'error')) process.exitCode = 2;
+} catch (error) { process.stderr.write(error.message + '\n'); process.exitCode = 2; }

package/template/scripts/lib/approval-record.mjs

@@ -1,4 +1,5 @@
 import { assertApprovalUserDecision } from './user-decision-reuse.mjs';
+import { parseAsset, validateAssetStructure } from './structured-assets.mjs';
 import { existsSync, readFileSync } from './validation-phase.mjs';
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
@@ -31,9 +32,8 @@ function yamlFromFile(filePath, label) {
     if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
     throw error;
   }
-  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
-  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
-  const value = document.toJS({ maxAliasCount: 0 });
+  const value = parseAsset(source, filePath);
+  validateAssetStructure(value, 'approval-record');
   if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
   return value;
 }
@@ -79,6 +79,7 @@ export function resolveApprovalRef(approvalRef, fromFile = ROOT) {
 }
 
 export function validateApprovalRecord(record, { rolesDoc, requireApproved = false, ...decisionOptions } = {}) {
+  validateAssetStructure(record, 'approval-record');
   if (!record || typeof record !== "object" || Array.isArray(record)) fail("会签记录必须是对象");
   if (record.schema_version !== 1) fail("会签记录 schema_version 必须为 1");
   requireString(record.gate_id, "gate_id");

package/template/scripts/lib/asset-command.mjs

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { readAsset, parseAsset, serializeAsset } from './structured-assets.mjs';
+import { safeFile } from './governance-io.mjs';
+import { planAssetWrite, applyAssetWrite, recoverAssetWrite, validateAssetSemantics, assertAssetTransactionIdle, assertCurrentAssetReference } from './asset-transactions.mjs';
+import { planAssetMigration, applyAssetMigration } from './asset-migration.mjs';
+
+export const isAssetCommand = command => ['validate','plan-write','apply-write','plan-migrate','apply-migrate','recover'].includes(command);
+export function runAssetCommand(args) {
+  const command = args.shift();
+  const {values, positionals} = parseArgs({ args, allowPositionals: true, strict: true, options: { root:{type:'string'},kind:{type:'string'},input:{type:'string'},output:{type:'string'},resolutions:{type:'string'},'structure-only':{type:'boolean'} } });
+  const root = path.resolve(values.root || process.cwd());
+  const input = file => parseAsset(fs.readFileSync(path.resolve(file)), file);
+  let result;
+  if (command === 'recover') { if (positionals.length) throw new Error('recover takes --root only'); result = recoverAssetWrite(root); }
+  else {
+    if (positionals.length !== 1) throw new Error(`${command} requires one asset/plan path`);
+    const ref = positionals[0];
+    if (command === 'validate') {
+      assertAssetTransactionIdle(root);
+      assertCurrentAssetReference(root,ref);
+      const record = readAsset(safeFile(root, ref), values.kind, {schemaRoot:root});
+      result = {status:'valid',kind:values.kind,ref,digest:record.digest,checks:['schema'],execution_authorization:'not-granted'};
+      if (!values['structure-only']) {result.verification=validateAssetSemantics(root,ref,values.kind);result.checks.push('consumer');}
+    } else if(command === 'plan-write') {
+      if (!values.input) throw new Error('plan-write <target.json> --kind <kind> --input <candidate.json>');
+      result = planAssetWrite(root,[{ref,kind:values.kind,value:input(values.input)}],{schemaRoot:root});
+    } else if(command === 'apply-write') result = applyAssetWrite(root,input(ref));
+    else if(command === 'plan-migrate') result = planAssetMigration(root,ref,{schemaRoot:root});
+    else result = applyAssetMigration(root,input(ref),values.resolutions?input(values.resolutions):undefined,{schemaRoot:root});
+  }
+  if(values.output) fs.writeFileSync(path.resolve(values.output),serializeAsset(result),{flag:'wx'});
+  return result;
+}

package/template/scripts/lib/asset-migration.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { safeFile } from './governance-io.mjs';
+import { parseAsset, readAsset, serializeAsset, byteDigest, semanticDigest, assetComments, TOOL_ROOT } from './structured-assets.mjs';
+import { planAssetWrite, applyAssetWrite, assertAssetTransactionIdle } from './asset-transactions.mjs';
+
+export function identifyAsset(value) {
+  if (value.stage_decision_id) return 'stage-decision-package';
+  if (value.domain_strategy_id) return 'domain-strategy';
+  if (value.task_id && value.contract && value.execution_state) return 'task-package';
+  if (value.gate_id && value.decision || value.kind === 'review-bundle') return 'approval-record';
+  if (value.repository_mode && value.stage && value.gates) return 'checkpoint';
+  return null;
+}
+const immutable = key => ['verification', 'result', 'source', 'captures', 'history', 'git_checkpoint'].includes(key);
+function refs(value, out = new Set(), key = '') {
+  if (immutable(key)) return out;
+  if (typeof value === 'string' && /(?:^ref$|_ref$|_refs$|^inputs$)/.test(key) && /\.(yaml|json)$/.test(value)) out.add(value);
+  else if (Array.isArray(value)) value.forEach(v => refs(v, out, key));
+  else if (value && typeof value === 'object') for (const [name, child] of Object.entries(value)) refs(child, out, name);
+  return out;
+}
+function replaceRefs(value, mapping, key = '') {
+  if (immutable(key)) return structuredClone(value);
+  if (typeof value === 'string' && /(?:^ref$|_ref$|_refs$|^inputs$)/.test(key)) return mapping[value] || value;
+  if (Array.isArray(value)) return value.map(v => replaceRefs(v, mapping, key));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([name, child]) => [name, replaceRefs(child, mapping, name)]));
+  return value;
+}
+
+/** Produces reviewable candidates, never approval or a second live checkpoint. */
+export function planAssetMigration(root, checkpointRef, { schemaRoot = TOOL_ROOT } = {}) {
+  root = fs.realpathSync(root); assertAssetTransactionIdle(root);
+  const queue = [checkpointRef], sources = {}, candidates = [], blockers = [], currentJson = [];
+  while (queue.length) {
+    const ref = queue.shift(); if (Object.hasOwn(sources, ref)) continue;
+    const file = safeFile(root, ref);
+    if (!fs.existsSync(file)) { blockers.push({ code: 'missing-reference', ref }); continue; }
+    const bytes = fs.readFileSync(file), value = parseAsset(bytes, ref), kind = identifyAsset(value);
+    if (!kind) continue; // Original user messages and other evidence keep their format and bytes.
+    sources[ref] = byteDigest(bytes);
+    // Completed execution packages and old reviews remain immutable evidence.
+    if (kind === 'task-package' && ['resolved', 'failed'].includes(value.workflow_status)) continue;
+    readAsset(file, kind, { schemaRoot });
+    queue.push(...refs(value));
+    if (ref.endsWith('.json')) { currentJson.push({ref,value,kind,bytes}); continue; }
+    const target = ref.replace(/\.yaml$/, '.json');
+    if (fs.existsSync(safeFile(root, target))) { blockers.push({ code: 'target-exists', ref: target }); continue; }
+    const comments = assetComments(bytes);
+    if (comments.length) blockers.push({ code: 'comment-review-required', ref, comments });
+    candidates.push({ source_ref: ref, ref: target, kind, source_digest: byteDigest(bytes), source_semantic_digest: semanticDigest(value), value });
+  }
+  const mapping = Object.fromEntries(candidates.map(c => [c.source_ref, c.ref]));
+  for (const item of currentJson) if (semanticDigest(item.value) !== semanticDigest(replaceRefs(item.value, mapping))) {
+    if (item.kind === 'approval-record') blockers.push({code:'current-json-reference-rebind-required',ref:item.ref,reason:'Issue a new approval record; an existing approval is immutable.'});
+    else candidates.push({source_ref:item.ref,ref:item.ref,kind:item.kind,source_digest:byteDigest(item.bytes),source_semantic_digest:semanticDigest(item.value),value:item.value});
+  }
+  for (const c of candidates) {
+    c.value = replaceRefs(c.value, mapping);
+    if (c.kind === 'approval-record' || ['domain-strategy', 'stage-decision-package'].includes(c.kind) && c.value.status === 'approved') {
+      blockers.push({ code: 'approval-rebind-required', ref: c.ref, reason: 'Candidate bytes do not inherit the source approval; issue independent current evidence.' });
+    }
+  }
+  // Updating digests is mechanical only for direct current bindings, not historical proof.
+  const byTarget = new Map(candidates.map(c => [c.ref, c]));
+  const ordered = candidates.sort((a,b) => ['domain-strategy','approval-record','stage-decision-package','task-package','checkpoint'].indexOf(a.kind) - ['domain-strategy','approval-record','stage-decision-package','task-package','checkpoint'].indexOf(b.kind));
+  function bind(value, key = '') {
+    if (!value || typeof value !== 'object' || immutable(key)) return;
+    if (value.domain_strategy_ref && byTarget.has(value.domain_strategy_ref.persisted_ref)) value.domain_strategy_ref.digest = semanticDigest(byTarget.get(value.domain_strategy_ref.persisted_ref).value);
+    if (typeof value.ref === 'string' && typeof value.digest === 'string' && byTarget.has(value.ref)) value.digest = byteDigest(serializeAsset(byTarget.get(value.ref).value));
+    for (const [name, child] of Object.entries(value)) bind(child, name);
+  }
+  for (const c of ordered) bind(c.value);
+  const payload = { schema_version: 1, kind: 'asset-migration-plan', root, checkpoint_ref: checkpointRef, sources, candidates: ordered, blockers, history_policy: 'preserve-original-bytes', execution_authorization: 'not-granted' };
+  return { ...payload, plan_id: byteDigest(serializeAsset(payload)).slice(7) };
+}
+
+/** Resolutions carry reviewed candidate objects and evidence; they do not bypass semantic validators. */
+export function prepareAssetMigrationWrite(root, plan, resolutions, options = {}) {
+  const { plan_id, ...payload } = plan;
+  if (fs.realpathSync(root) !== plan.root || plan.kind !== 'asset-migration-plan' || plan_id !== byteDigest(serializeAsset(payload)).slice(7)) throw new Error('ASSET_MIGRATION_PLAN_INVALID');
+  for (const [ref, digest] of Object.entries(plan.sources)) if (byteDigest(fs.readFileSync(safeFile(root, ref))) !== digest) throw new Error(`ASSET_MIGRATION_DRIFT: ${ref}`);
+  if (plan.blockers.some(b => ['missing-reference', 'target-exists', 'current-json-reference-rebind-required'].includes(b.code))) throw new Error('ASSET_MIGRATION_BLOCKED: rebuild the plan after resolving missing/conflicting inputs');
+  if (plan.blockers.length && (!resolutions || resolutions.plan_id !== plan_id)) throw new Error('ASSET_MIGRATION_REVIEW_REQUIRED');
+  for (const b of plan.blockers) {
+    const resolution = resolutions.items?.find(r => r.ref === b.ref && r.code === b.code);
+    if (!resolution?.evidence_ref || !resolution.evidence_digest || byteDigest(fs.readFileSync(safeFile(root, resolution.evidence_ref))) !== resolution.evidence_digest) throw new Error(`ASSET_MIGRATION_EVIDENCE_REQUIRED: ${b.ref}`);
+  }
+  const replacements = resolutions?.candidates || [];
+  for (const replacement of replacements) if (!plan.candidates.some(c => c.ref === replacement.ref && c.kind === replacement.kind)) throw new Error('ASSET_MIGRATION_SCOPE_CHANGED');
+  const specs = plan.candidates.map(c => replacements.find(r => r.ref === c.ref) || c);
+  const migration={plan_id:plan.plan_id,sources:plan.sources,source_to_target:Object.fromEntries(plan.candidates.filter(c=>c.source_ref!==c.ref).map(c=>[c.source_ref,c.ref]))};
+  return planAssetWrite(root, specs, {...options,migration});
+}
+
+export function applyAssetMigration(root, plan, resolutions, options = {}) {
+  const writePlan = prepareAssetMigrationWrite(root, plan, resolutions, options);
+  const result = applyAssetWrite(root, writePlan, options);
+  const updated = new Set(writePlan.changes.filter(c => Object.hasOwn(plan.sources,c.ref)).map(c => c.ref));
+  return { ...result, migration_plan_id: plan.plan_id, preserved_sources: Object.keys(plan.sources).filter(ref => !updated.has(ref)), rebound_json_sources: [...updated] };
+}