create-yss-spec 3.5.4 → 3.5.5

package/README.md

@@ -188,3 +188,11 @@ npm pack --dry-run
 ## 治理目录迁移
 
 新实例将分发治理资产安装到 `.template-spec/`，项目规格产物放在 `docs/`。已有实例只有显式运行 `sync --migrate-layout --plan` 审阅后，才运行 `sync --migrate-layout --apply`；`attach` 同样支持该开关。迁移保留项目 tracker 配置，缺少可信摘要、旧文件被修改或目标路径冲突时阻断。普通 sync 不自动改变旧实例目录。
+
+## 固定计划实例迁移
+
+`migrate plan --target-dir <项目绝对路径> --output <项目外新计划.json>` 生成项目只读计划；`migrate apply --plan <计划>` 执行固定候选并保存持久归档。计划后输入变化必须重新规划。需要旧布局迁移或安全退出分发清理时，规划阶段显式加入 `--migrate-layout` / `--prune`。
+
+`migrate status` 查看状态；`migrate recover` 预览中断恢复，`migrate rollback` 预览最近一次成功迁移的整体回退，均需显式 `--apply` 才写入。后续修改、跨家族、未知基线及损坏归档阻断，禁止用 force 绕过。所有新接口支持 `--json`。
+
+旧实例无需先 sync 安装技能：从当前固定版本包的 `resources/upgrade-skill/SKILL.md` 在项目外读取升级入口及相邻 `protocol.md`。默认归档保留于用户目录 `.yss-harness/archives/`；不自动清理。CLI 程序 update/upgrade 与实例迁移相互独立。

package/cli-core.lock.json

@@ -0,0 +1,130 @@
+{
+  "schemaVersion": 1,
+  "sourceRepository": "https://github.com/iloveZzz/yss-spec-project-template.git",
+  "sourceRevision": "b98bafda74fc60c2b41c6020e3d41d84a4f1b1b7",
+  "sourceState": "committed",
+  "sourcePath": ".template-source/cli-core",
+  "coreVersion": "0.2.0",
+  "protocolVersion": 1,
+  "files": {
+    "build.mjs": {
+      "digest": "5f869fecc2f30767c31222e8594456f59671a0744f5a58e95bafaa6338adddbe",
+      "mode": 420
+    },
+    "bundle.mjs": {
+      "digest": "4d60b5f9c10c3487c4e3817a9fd9597734249eb7244cc98f53f4741a1e63a3ce",
+      "mode": 420
+    },
+    "cli.mjs": {
+      "digest": "73aae345737aa7d069283ff7e5539be26498c7a7c94d1100a699a47e4c18e31f",
+      "mode": 420
+    },
+    "command-runner.mjs": {
+      "digest": "4fb7f3c9ca26dff3f955ddb1c6ad545519d3e55af179f834ff67b1c0bf20bffd",
+      "mode": 420
+    },
+    "engine.mjs": {
+      "digest": "70fae490df46a19148a017322ef12f27e6d58d28c7f48fb476ef178dc091dac2",
+      "mode": 420
+    },
+    "family.mjs": {
+      "digest": "2a21348f54e2f8e8f81e1000e3228b3fe3e8817a78244f9866c150318fd129d0",
+      "mode": 420
+    },
+    "gitignore.mjs": {
+      "digest": "dc781dffad8bcff81fd3967546fa8e824641b80d38d47a06eb0909e3401b2940",
+      "mode": 420
+    },
+    "identity.mjs": {
+      "digest": "d1d41fa42aac6ec5cf3e237d1807237f43252b3308e169a838fd3c735f3475ac",
+      "mode": 420
+    },
+    "io.mjs": {
+      "digest": "7edc2095f05086fbff90e6a722950fb6ef57468593a1971bc96a791632457746",
+      "mode": 420
+    },
+    "layout-migration.mjs": {
+      "digest": "0dd1569c43b11c8e4384e7994ac7f6185236756b7297a0a06e867e972b2b036b",
+      "mode": 420
+    },
+    "legacy.mjs": {
+      "digest": "ac5652dee0f3a6d0204a0dad3b0b3a7531a962f620768b72c6aed0d610c446ed",
+      "mode": 420
+    },
+    "migrate.mjs": {
+      "digest": "43788e3916ea95b2800290c70eab3fdd45d1d730705c4a8fadf76dbe8b864304",
+      "mode": 420
+    },
+    "migration-adapter.mjs": {
+      "digest": "43cab1bdeda56859d604f4bbe6d818444c27166d08c6617bac3667c4dd0a3a9d",
+      "mode": 420
+    },
+    "package.json": {
+      "digest": "68d3dfd6451f7a433ff2eb821daa83d59e0c03f19b73d3a2cf5582ee6ce23332",
+      "mode": 420
+    },
+    "scaffold.mjs": {
+      "digest": "ebf16b3ffe95fe00698691ebc71362dfce1e93846a34cb01745b0c063035e209",
+      "mode": 420
+    },
+    "spec-migration-adapter.mjs": {
+      "digest": "45f0bae94552522999abeabef69b9e93220755a089b2a508dcd1a077af07d363",
+      "mode": 420
+    },
+    "tests/build.test.mjs": {
+      "digest": "af6bd15ef81f5160bf94a85ad19cd3d3763b80c8eb577229c9a9b47564e902f6",
+      "mode": 420
+    },
+    "tests/cli.test.mjs": {
+      "digest": "a51dc4bdbc1220bf6c720bd63a05fdbf82101330b012eb535d5b7e6b1ff3693a",
+      "mode": 420
+    },
+    "tests/migration-version.test.mjs": {
+      "digest": "be0389cba634e013f8f7192243057a29e58fe49f3d33372e31eceb96788e001b",
+      "mode": 420
+    },
+    "tests/package-contract.mjs": {
+      "digest": "812129d3c327515269ed2aff08fec97049aa306b65f752d47a3cd004a168be72",
+      "mode": 420
+    },
+    "transaction.mjs": {
+      "digest": "f2fbc4642e953ce00cece2e9f9fe61b7b50f42fabed41e64d5a1902d0ae660a8",
+      "mode": 420
+    },
+    "update.mjs": {
+      "digest": "10a68ac1a709ab3748f9c7e615bc9eeaae82cab9d35077349c13d2ecccd7a111",
+      "mode": 420
+    },
+    "vendor/NOTICES.md": {
+      "digest": "7eba5e5f046d1c0b1c7c02ff036925d2580682c67e09b5521c8fc4f284f3b216",
+      "mode": 420
+    },
+    "vendor/yaml.LICENSE": {
+      "digest": "5bba27375d93e9119f76c1015f7672cf9ad5f70952296e0842fb2243d6376869",
+      "mode": 420
+    },
+    "vendor/yaml.mjs": {
+      "digest": "58c510627769ef4e75e90bcf410d63ba33e64b46bc9cfc53149839d5ccb1709b",
+      "mode": 420
+    },
+    "verification.mjs": {
+      "digest": "e029c8f57b756b4d8709e8b05871b3a09ea8716c71ca93dda0b3480b932b662f",
+      "mode": 420
+    }
+  },
+  "digest": "f5199dba3f9dc94a9b2e92a8b4d65d0633a5a3dfc489d88d30cb461204b8d63d",
+  "upgradeResources": {
+    "SKILL.md": {
+      "digest": "40495ca033ebd0345363714e45571ee77258a435ea1523ae716dc2402ced0487",
+      "mode": 420
+    },
+    "protocol.md": {
+      "digest": "34367c4618617dadb6151bb569bd93616e55bc718d08dc8805e94cdb56cf0a6c",
+      "mode": 420
+    },
+    "references/cli-families.md": {
+      "digest": "70321868fd21c99944c36e8ce9882c5f4910bbe382d2ecfdb8c5c04d5dbe00d4",
+      "mode": 420
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {
@@ -16,7 +16,10 @@
     "src",
     "template",
     "template.manifest.json",
-    "template.snapshot.json"
+    "template.snapshot.json",
+    "vendor/cli-core",
+    "cli-core.lock.json",
+    "resources/upgrade-skill"
   ],
   "bin": {
     "create-yss-spec": "bin/create-yss-spec.js"
@@ -29,7 +32,8 @@
     "test:unit": "node --test tests/*planner*.test.js tests/filesystem-*.test.js tests/validation-modules.test.js tests/doctor-checks.test.js tests/ownership-policy.test.js tests/lifecycle-policy.test.js tests/lifecycle-metadata.test.js tests/verification-runtime.test.js tests/cli-modules.test.js tests/cli-entrypoint.test.js tests/self-update.test.js tests/plan-schema.test.js tests/contracts.test.js tests/error-output.test.js tests/apply-result-contract.test.js tests/programmatic-api-unit.test.js",
     "test:integration": "npm run sync-template && node --test tests/init-cli.test.js tests/sync-command-modular.test.js tests/attach-command-modular.test.js tests/doctor-diff-command.test.js tests/programmatic-api.test.js tests/family-identity.test.js",
     "prepack": "node scripts/sync-template.js --require-committed",
-    "test:prepared": "node --test --test-concurrency=1 tests/*.test.js"
+    "test:prepared": "node --test --test-concurrency=1 tests/*.test.js",
+    "sync-core": "node scripts/sync-core.mjs"
   },
   "devDependencies": {
     "ajv": "^8.20.0"

package/resources/upgrade-skill/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: yss-harness-upgrade
+description: 升级既有 YSS 模板实例，规划同家族版本迁移、定制合并、持久归档、验证与恢复；用于 create-yss-spec 及 design/backend/frontend CLI 实例升级，不处理业务代码或数据库迁移。
+---
+
+# YSS 实例升级
+
+先读取根 `yss-project.yaml`、`CONTEXT.md` 和 [统一协议](protocol.md)。目标必须是已登记的同家族 `project-instance`；身份/schema 不支持时只诊断，不能重新 init 或猜测身份。模板源的技能维护由 `maintaining-skills` 处理。
+
+## 工作顺序
+
+1. 确认目标绝对路径、用户授权范围、实际 CLI 路径及版本、模板 metadata、工作区已有改动。依据 [家族适配](references/cli-families.md) 选定 CLI。未指定目标版本时查询同家族稳定版本并固定精确包版本和摘要，执行期间不再引用 `latest`。CLI 程序升级和项目实例迁移分别记录，不自动安装全局版本。
+2. 用固定 CLI 的 `migrate status` 检查中断事务。有中断时先 `migrate recover` 预览，按既有授权执行 `--apply`，然后重新规划。不得删除状态目录绕过恢复。
+3. `migrate plan --target-dir <绝对路径> --output <项目外全新计划.json>`。旧治理布局迁移显式附加 `--migrate-layout`；退出分发文件清理显式附加 `--prune`。计划阶段不修改项目；检查计划中的版本、变化路径、保留项和归档位置。
+4. 冲突时在项目外起草候选差异和 `--resolutions` 文件。只使用计划报告的可信受管冲突；`preserve` 保留原文，`merge` 提供候选内容并绑定原文件及新模板摘要。向用户展示新的语义取舍，复用已有范围授权；未获授权的新决定保持等待。不能使用 `--force` 批量覆盖，不能先修改项目来消除冲突。
+5. 用相同固定 CLI 执行 `migrate apply --plan <计划>`。执行器重新生成候选并验证计划、归档、身份和输入摘要；`STALE_PLAN` 时重新规划，不能手改摘要续跑。迁移不自动 commit、stash、reset、push 或发布。
+6. 查看回执和实例验证结果，执行相同选项的新计划验证无重复迁移。核对业务文件与既有工作区改动保持，说明保留的定制和现有失败。输出实际版本、归档/回执位置、验证证据和剩余问题；结构检查不能代替真实 CLI 或 Agent 行为验证。
+
+## 恢复与边界
+
+- `migrate recover` 恢复未完成事务；`migrate rollback` 预览最近一次成功迁移的整体回退。两者仅加 `--apply` 才写入。回退遇到后续修改或损坏归档必须保留现场，不覆盖新工作。
+- Spec、Ticket、合同、人工回复、批准和正式验证默认保留。路径迁移不产生新批准；语义或批准绑定变化交回原生命周期，不补造旧状态。
+- 不执行跨家族转换、任意历史版本跳转、业务重构或数据库迁移。未知基线不能由 Agent 猜测；归档不能作为扩大写入授权的理由。
+- 旧实例缺少本技能时，从已固定 CLI 包的 `resources/upgrade-skill/` 在项目外读取入口及相邻协议。不得先同步目标项目来安装升级技能。
+
+本技能只编排，不复制迁移执行器。研究新技术事实时用 `yss-research`；结论输出按 `lifecycle-document-output` 使用 `i-have-adhd`。不批准 Slice、不设置 `ready-for-agent`、不宣称可发布。

package/resources/upgrade-skill/protocol.md

@@ -0,0 +1,40 @@
+# YSS 模板实例升级协议
+
+本协议定义 `yss-harness-upgrade` 与四类 YSS CLI 的同家族实例升级。技能负责判断、冲突方案和授权范围；CLI 负责计划校验、候选验证、持久归档、事务和恢复。历史批准及 Ticket 状态仍由各自权威协议管理。
+
+## 输入与接口
+
+固定精确 CLI 版本、包内容及模板快照，确认真实项目根、metadata/schema、profile、受管基线和 Git 状态。旧版本缺少受支持的基线/schema 时停止，不重新初始化。目标模板使用所执行 CLI 的内置快照；不在 apply 阶段查询 latest 或运行外部计划提供的脚本。
+
+- `migrate plan --target-dir <绝对目录> --output <项目外全新文件> [--archive-dir <项目外全新目录>] [--migrate-layout] [--prune] [--resolutions <文件>]`：项目只读，在项目外生成固定计划；冲突返回机器可读诊断。
+- `migrate apply --plan <文件> [--target-dir <同一目录>]`：显式执行。
+- `migrate status --target-dir <目录>`：只读状态。
+- `migrate recover|rollback --target-dir <目录> [--apply]`：默认只读预览，显式写入。
+
+所有命令接受 `--json`，输出 schemaVersion 1 JSON。失败非零退出；区分 `CONFLICT`、`STALE_PLAN`、`EXECUTOR`、`PLAN`、`ARCHIVE`、`INTERRUPTED`、`CONCURRENT`、`RECOVERY_FAILED` 等。原 CLI 命令及错误协议保持兼容。
+
+## 计划与冲突
+
+计划绑定 schemaVersion、事务 ID、时间、项目根、家族、执行器摘要、目标模板、归档位置、迁移选项、输入清单、Git HEAD/index/gitlink、规则 ID、操作前后内容/权限摘要和候选内容。整体 planDigest 检测意外修改；执行器还重新生成候选操作，不信任手改计划或重新计算摘要。摘要不等于授权。
+
+版本化规则 `managed-sync.v1`、`layout-migration.v1`、`retirement.v1` 复用各 CLI 原有身份/schema 范围和可信文件基线判定；后两者分别要求显式布局迁移与 prune。不凭名称或目录推断旧资产属于模板，不提供未知旧版本的猜测迁移。
+
+`resolutions` 为路径到决议的 JSON 映射。每项包含 `action: preserve|merge`、`beforeDigest`、`templateDigest`；merge 另含候选字节的 `contentBase64`。只接受确实存在、有可信基线且可合并的受管冲突；未知路径、受保护资产、过期摘要或未消费决议拒绝。技能在项目外起草合并差异，新增语义决定取得用户回复后重新生成计划。CLI 不把决议文件当成人工批准。
+
+未修改受管文件自动更新。修改过的退出分发文件保留；`--prune` 只删除仍匹配旧基线的文件。项目拥有的 tracker、业务文档和已批准资产按现有保护规则保留；历史冻结和批准不会因路径移动获得新的有效性。
+
+## 归档、执行与恢复
+
+默认归档位置为 `~/.yss-harness/archives/<项目路径与家族摘要>/<事务ID>/`，可显式改为项目外全新目录。保存 plan.json、before/ 原字节与权限、receipt.json；首版不自动清理归档。布局迁移额外保存 project-copy/ 项目内容副本；不跟随符号链接，排除 Git 内部数据、依赖、索引缓存及事务状态，这些排除项不是迁移写入范围。Git 工作区和索引不重建、不 reset、不 stash。
+
+候选操作先在隔离副本中完成生成锁文件与实例校验。真实执行前重新核验输入，先归档并校验，再在互斥锁下写入。内部事务日志预写并持久化，文件、生成锁及 metadata 属于同一事务。既有业务文件和无关未提交/未跟踪工作保持；输入漂移要求新计划。
+
+内部 `.yss-harness-state/upgrade.json` 索引关联外部回执与事务。失败自动恢复本次写入；进程中断后 recover 校验事务和备份再恢复。成功提交但回执尚未完成的情况依据持久日志收敛状态。保留损坏、冲突及未恢复路径，不把恢复失败写成成功。
+
+rollback 只针对索引中最近一次成功迁移，完整预检全部原件和升级后状态后才开始。任何后续修改、丢失或损坏备份都会阻断；不提供忽略冲突的 force。回退使用新的可恢复事务，不更改 CLI 安装版本。重复 apply 只有在同一计划已成功且结果仍匹配时才返回原回执；恢复或回退后的旧计划不复用。
+
+## 验证与结论
+
+校验身份、布局、Context、Skill 锁和投影等各家族现有实例合同；有失败不跳过。对未迁移资产与 Git index/HEAD/gitlink 做并发检查。迁移完成再规划，证明不会重复执行；计划保留项不是自动消失的冲突。
+
+回执说明实际版本、范围、归档、事务状态和验证结果。原有失败与新增失败分别说明；升级成功不表示产品阶段批准或发布就绪。提交、推送、发布及真实项目迁移均按会话授权，不由技能或计划摘要授予。

package/resources/upgrade-skill/references/cli-families.md

@@ -0,0 +1,14 @@
+# 同家族升级适配
+
+| CLI | 实例 metadata |
+|---|---|
+| create-yss-spec | .yss-template.json |
+| create-yss-harness-design | .yss-harness-design.json |
+| create-yss-harness-backend | .yss-harness-backend.json |
+| create-yss-harness-frontend | .yss-harness-frontend.json |
+
+身份还需通过各 CLI 原有 profile/schema 检查。多个 metadata、旧 dev 家族、未知 schema、符号链接或矛盾 profile 均不能自动接管。`migrate` 不是降级或跨家族工具。
+
+四类 CLI 的新入口一致：`migrate plan|apply|status|recover|rollback`，支持 `--json`。`migrate plan` 只向显式指定的项目外新文件输出；`apply --plan <文件>` 显式写入。recover/rollback 默认只读，写入需 `--apply`。不要从旧 `sync` 推断新接口：主 CLI 普通 sync 会写入，专职 CLI sync 默认预览。
+
+目标模板来自当前固定 CLI 包，不接受计划中的下载地址或脚本。版本、模板和执行器摘要不匹配时更换为生成计划的原包，或重新规划；不得修改计划来绕过。已有 `update/upgrade` 仅更新 CLI 程序，既有 `recover` 仍只恢复原事务。

package/src/cli/help.js

@@ -13,6 +13,7 @@ USAGE
 COMMANDS
   (default)  初始化新的模板实例仓库
   attach     向已有项目补齐受管研发管理资产
+  migrate    固定计划升级：plan/apply/status/recover/rollback
   sync       同步已有模板实例的受管资产
   diff       只计算同步差异，不写入文件
   doctor     检查模板实例、身份、Git 和安全状态

package/src/cli/index.js

@@ -37,6 +37,18 @@ const { resolveCommand } = require("./router");
 const PACKAGE_ROOT = path.resolve(__dirname, "../..");
 
 async function runCli(argv = []) {
+  if (argv[0] === "migrate") {
+    const { runSpecMigration } = await import("../../vendor/cli-core/spec-migration-adapter.mjs");
+    try {
+      const result = runSpecMigration(PACKAGE_ROOT, argv.slice(1));
+      process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      return result;
+    } catch (error) {
+      process.stdout.write(JSON.stringify({schemaVersion:1,command:"migrate",status:"error",code:error.code || "INVALID",message:error.message,...(error.result?{diagnostic:error.result}:{})},null,2)+"\n");
+      process.exitCode=1;
+      return;
+    }
+  }
   const route = resolveCommand(argv);
 
   if (route.command === "help") {

package/src/filesystem/transaction-runner.js

@@ -1,5 +1,30 @@
 "use strict";
 
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+function withProjectLock(targetDir, execute) {
+  const index = path.join(targetDir, ".yss-harness-state/upgrade.json");
+  if (fs.existsSync(index)) {
+    const state = JSON.parse(fs.readFileSync(index, "utf8"));
+    if (!Array.isArray(state.runs) || state.runs.some(run => ["applying", "rolling-back"].includes(run.phase))) throw new Error("请先使用 migrate recover 恢复未完成迁移");
+  }
+  const file = path.join(targetDir, ".yss-harness-migrate.lock");
+  if (fs.existsSync(file)) {
+    const info = fs.lstatSync(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) throw new Error("迁移锁不是普通文件");
+    const owner = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (owner.host !== os.hostname() || !Number.isInteger(owner.pid) || owner.pid <= 0) throw new Error("未知迁移锁持有者");
+    let alive = true;
+    try { process.kill(owner.pid, 0); } catch (error) { if (error.code === "ESRCH") alive = false; else throw error; }
+    if (alive) throw new Error("另一个同步或迁移正在运行");
+    fs.unlinkSync(file);
+  }
+  const fd = fs.openSync(file, "wx", 0o600);
+  fs.writeFileSync(fd, JSON.stringify({pid:process.pid,host:os.hostname()}));
+  fs.fsyncSync(fd); fs.closeSync(fd);
+  try { return execute(); } finally { fs.unlinkSync(file); }
+}
 const { FileTransaction } = require("./transaction");
 
 function runInTransaction({
@@ -13,6 +38,7 @@ function runInTransaction({
     throw new TypeError("runInTransaction requires execute callback");
   }
 
+  return withProjectLock(targetDir, () => {
   const transaction = new TransactionClass(targetDir);
 
   try {
@@ -34,6 +60,7 @@ function runInTransaction({
       `${error.message}\n已回滚本次 ${operation}；临时备份保留于 ${transaction.backupRoot}`,
     );
   }
+  });
 }
 
 module.exports = {

package/src/template/asset-runtime.js

@@ -26,6 +26,11 @@ const COMMON = {
     ".template-spec/process/harness-process-tailoring.md",
     ".template-spec/process/document-writing.md",
     ".template-spec/process/contract-reading.md",
+    ".template-spec/process/structured-assets.md",
+    ".template-spec/process/schemas/approval-record.schema.json",
+    ".template-spec/process/schemas/review-bundle.schema.json",
+    ".template-spec/process/templates/lifecycle-checkpoint-template.json",
+    ".template-spec/templates/approval-record-template.json",
     ".template-spec/process/reading-policy.yaml",
     ".template-spec/process/schemas/reading-policy.schema.json",
     ".template-spec/process/schemas/reading-manifest.schema.json",
@@ -66,6 +71,7 @@ const COMMON = {
     "scripts/prepare-read-only-intake",
     "scripts/run-read-only-intake",
     "scripts/contract",
+    "scripts/check-plan-stage-coverage",
     "scripts/stage-tracking",
     "scripts/project-ci",
     "scripts/project-ci-transition",

package/src/template/verification-runtime.js

@@ -39,6 +39,13 @@ function initializeGitRepository(targetDir) {
   }
 }
 
+let verificationOutput = (text) => process.stdout.write(text);
+function withVerificationOutput(writer, execute) {
+  const previous = verificationOutput;
+  verificationOutput = writer;
+  try { return execute(); } finally { verificationOutput = previous; }
+}
+
 function runTemplateVerification(targetDir, scriptPath, args = ["--check"]) {
   const commandPath = targetPath(targetDir, scriptPath);
   const result = spawnSync(commandPath, args, {
@@ -48,7 +55,7 @@ function runTemplateVerification(targetDir, scriptPath, args = ["--check"]) {
   });
   const output = [result.stdout, result.stderr].filter(Boolean).join("");
   if (output) {
-    process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+    verificationOutput(output.endsWith("\n") ? output : `${output}\n`);
   }
   if (result.status !== 0) {
     const detail = result.error?.message || output.trim();
@@ -193,6 +200,7 @@ function refreshGeneratedProjectInstance(targetDir, options = {}) {
 }
 
 module.exports = {
+  withVerificationOutput,
   verificationEnvironment,
   initializeGitRepository,
   runTemplateVerification,

package/template/.agents/skills/.strategic-design-skills-manifest.json

@@ -3,7 +3,7 @@
   "source": "iloveZzz/yss-harness-design-agent",
   "source_type": "git-submodule",
   "source_root": ".agents/skills",
-  "source_revision": "d754260a597df6bc342f2411ccfd5bcf94a307e9",
+  "source_revision": "fbe4084276a8fe9a8f59e58481f2913133346eaf",
   "adaptation_ref": ".template-source/agents/strategic-design-skills-integration.md",
   "skills": [
     {
@@ -24,7 +24,7 @@
     {
       "upstream": "yss-stage-decision",
       "canonical": "yss-stage-decision",
-      "upstream_hash": "9e06107a37c2251b454bde7e258f2e462ba5fe766f9fabe9e7f76419b60f5c98"
+      "upstream_hash": "77fa3075f90966821881998ff5fa9d674672bd2568e70b8d877402efeb360453"
     }
   ],
   "source_state": "committed"

package/template/.agents/skills/yss-harness-upgrade/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: yss-harness-upgrade
+description: 升级既有 YSS 模板实例，规划同家族版本迁移、定制合并、持久归档、验证与恢复；用于 create-yss-spec 及 design/backend/frontend CLI 实例升级，不处理业务代码或数据库迁移。
+---
+
+# YSS 实例升级
+
+先读取根 `yss-project.yaml`、`CONTEXT.md` 和 [统一协议](../../../.template-spec/process/harness-upgrade.md)。目标必须是已登记的同家族 `project-instance`；身份/schema 不支持时只诊断，不能重新 init 或猜测身份。模板源的技能维护由 `maintaining-skills` 处理。
+
+## 工作顺序
+
+1. 确认目标绝对路径、用户授权范围、实际 CLI 路径及版本、模板 metadata、工作区已有改动。依据 [家族适配](references/cli-families.md) 选定 CLI。未指定目标版本时查询同家族稳定版本并固定精确包版本和摘要，执行期间不再引用 `latest`。CLI 程序升级和项目实例迁移分别记录，不自动安装全局版本。
+2. 用固定 CLI 的 `migrate status` 检查中断事务。有中断时先 `migrate recover` 预览，按既有授权执行 `--apply`，然后重新规划。不得删除状态目录绕过恢复。
+3. `migrate plan --target-dir <绝对路径> --output <项目外全新计划.json>`。旧治理布局迁移显式附加 `--migrate-layout`；退出分发文件清理显式附加 `--prune`。计划阶段不修改项目；检查计划中的版本、变化路径、保留项和归档位置。
+4. 冲突时在项目外起草候选差异和 `--resolutions` 文件。只使用计划报告的可信受管冲突；`preserve` 保留原文，`merge` 提供候选内容并绑定原文件及新模板摘要。向用户展示新的语义取舍，复用已有范围授权；未获授权的新决定保持等待。不能使用 `--force` 批量覆盖，不能先修改项目来消除冲突。
+5. 用相同固定 CLI 执行 `migrate apply --plan <计划>`。执行器重新生成候选并验证计划、归档、身份和输入摘要；`STALE_PLAN` 时重新规划，不能手改摘要续跑。迁移不自动 commit、stash、reset、push 或发布。
+6. 查看回执和实例验证结果，执行相同选项的新计划验证无重复迁移。核对业务文件与既有工作区改动保持，说明保留的定制和现有失败。输出实际版本、归档/回执位置、验证证据和剩余问题；结构检查不能代替真实 CLI 或 Agent 行为验证。
+
+## 恢复与边界
+
+- `migrate recover` 恢复未完成事务；`migrate rollback` 预览最近一次成功迁移的整体回退。两者仅加 `--apply` 才写入。回退遇到后续修改或损坏归档必须保留现场，不覆盖新工作。
+- Spec、Ticket、合同、人工回复、批准和正式验证默认保留。路径迁移不产生新批准；语义或批准绑定变化交回原生命周期，不补造旧状态。
+- 不执行跨家族转换、任意历史版本跳转、业务重构或数据库迁移。未知基线不能由 Agent 猜测；归档不能作为扩大写入授权的理由。
+- 旧实例缺少本技能时，从已固定 CLI 包的 `resources/upgrade-skill/` 在项目外读取入口及相邻协议。不得先同步目标项目来安装升级技能。
+
+本技能只编排，不复制迁移执行器。研究新技术事实时用 `yss-research`；结论输出按 `lifecycle-document-output` 使用 `i-have-adhd`。不批准 Slice、不设置 `ready-for-agent`、不宣称可发布。

package/template/.agents/skills/yss-harness-upgrade/references/cli-families.md

@@ -0,0 +1,14 @@
+# 同家族升级适配
+
+| CLI | 实例 metadata |
+|---|---|
+| create-yss-spec | .yss-template.json |
+| create-yss-harness-design | .yss-harness-design.json |
+| create-yss-harness-backend | .yss-harness-backend.json |
+| create-yss-harness-frontend | .yss-harness-frontend.json |
+
+身份还需通过各 CLI 原有 profile/schema 检查。多个 metadata、旧 dev 家族、未知 schema、符号链接或矛盾 profile 均不能自动接管。`migrate` 不是降级或跨家族工具。
+
+四类 CLI 的新入口一致：`migrate plan|apply|status|recover|rollback`，支持 `--json`。`migrate plan` 只向显式指定的项目外新文件输出；`apply --plan <文件>` 显式写入。recover/rollback 默认只读，写入需 `--apply`。不要从旧 `sync` 推断新接口：主 CLI 普通 sync 会写入，专职 CLI sync 默认预览。
+
+目标模板来自当前固定 CLI 包，不接受计划中的下载地址或脚本。版本、模板和执行器摘要不匹配时更换为生成计划的原包，或重新规划；不得修改计划来绕过。已有 `update/upgrade` 仅更新 CLI 程序，既有 `recover` 仍只恢复原事务。

package/template/.agents/skills/yss-implementation-contract-compiler/references/boundaries.md

@@ -114,6 +114,7 @@
 | `yss-implementation-contract-compiler` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-openapi-governance` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-stage-decision` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
+| `yss-harness-upgrade` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-research` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `yss-product-lifecycle` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |
 | `code-review` | `i-have-adhd` | `context-conditional` | `lifecycle-document-output` |

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

@@ -7,27 +7,27 @@ description: 编排 YSS 研发全生命周期；当阶段、产物、门禁或 S
 
 合同阅读与托管更新：`scripts/contract view|render|check-views`；见 `.template-spec/process/contract-reading.md`。
 
-文档按 `document_writing` 条件调用 `i-have-adhd`，并传递 `.template-spec/process/document-writing.md` 规范。
+五类机器资产默认 JSON；读写、迁移及恢复须遵循 `.template-spec/process/structured-assets.md`。
 
-## 事实源与按需加载
+文档及进度按 `document_writing` 调用 `i-have-adhd`，遵循 `.template-spec/process/document-writing.md`；正文用中文名称与动作，编号按需追踪。
 
-先读 `yss-project.yaml`、`AGENTS.md`、`CONTEXT.md` 和当前任务视图，按需加载合同子树：
+## 事实源
+
+先读 `yss-project.yaml`、`AGENTS.md`、`CONTEXT.md` 和当前任务视图，按需读合同：
 
 | 事实 | 权威来源 |
 |---|---|
-| 阶段、聚合门禁、内部检查、产物、工作单元、证据和稳定 ID | `.template-spec/process/lifecycle-registry.yaml` |
-| 执行模式、流转、readiness、暂停、结果和授权语义 | `references/orchestration-contract.yaml` |
-| Skill 身份、capability、依赖和路由 | `.template-spec/agents/yss-skill-registry.yaml` |
+| 阶段、门禁、产物、工作单元、证据及 ID | `.template-spec/process/lifecycle-registry.yaml` |
+| 执行、流转和授权合同 | `references/orchestration-contract.yaml` |
+| Skill 身份、能力、依赖和路由 | `.template-spec/agents/yss-skill-registry.yaml` |
 | 数字人角色、运行时和会签策略 | `.template-spec/agents/digital-human-roles.yaml` |
-| 影响面、裁剪和模板维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
-
-查询合同：
+| 影响面、裁剪与维护强度 | `.template-spec/process/harness-process-tailoring.md`、`.template-source/process/maintenance-intensity.yaml` |
 
 ```bash
 scripts/query-lifecycle-context --mode route --stage stage.plan --work-unit work-unit.plan-requirements --include execution_efficiency
 ```
 
-`--include` 接受合同顶层键，非法键或 ID 失败。按需读 `references/orchestration.md` 及索引，证据充分即停止加载。
+`--include` 接受合同顶层键，非法输入失败。详见 `references/orchestration.md`。
 
 按 `execution_efficiency` 合并查询、复用未变资料；仍核验当前资产、词汇和门禁，产品流转不重跑模板套件。
 
@@ -71,27 +71,21 @@ Plan 入口读取 `.template-spec/plan/README.md` 和 `.template-spec/process/pl
 3. 原生工作单元由主控持有正式资产；专项按结构化任务包派发，只调用合同允许的 model-invoked skill。
 4. `to-spec`、`to-tickets`、`implement` 等兼容入口只可由用户显式调用。主控预检输入、路径和门禁；入口按 `matt_invocation_boundary` 写入其产物并回交验收，不批准或改变 Ticket 就绪状态。原生资产仍归主控。
 5. 先逐项验收用户目标、遗漏、错误假设和未决问题，再验收 `Workflow Execution Result`：工作单元、合同、允许写路径、`context_reconciliation`、证据、实际验证、延期 seam、漂移和下一路由必须可核验。实现派发额外绑定当前 Slice Implementation Contract v3；其他阶段不得伪造该合同。
-6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断无依赖的独立工作。
+6. 在授权边界内继续下一工作单元；遇到人工决定、新授权、证据冲突、专项失败或合并/发布结论时暂停。暂停不得阻断独立工作。
 
 每个 `project-instance` 工作单元批准或流转前，回写稳定术语到唯一根 `CONTEXT.md`，并生成通过校验的 `context_reconciliation`。候选术语、错误路径、摘要漂移或未决冲突必须阻断。质量标准只由 `engineering-baseline` 定义一次；高风险影响按裁剪合同补充反证和残余风险。
 
 ## 面向业务角色
 
-使用业务语言推进：
-
-`机会与目标 → 业务故事 → 责任与交接 → 规则、例子与疑问 → 可验收需求 → 页面验证 → 业务任务 → 交接研发`
-
 澄清目标、流程、责任、规则、范围和验收例子。业务总览引用权威资产，展示状态、未决项、责任人和下一步，不复制正文或新增门禁。
 
 Plan → Spec（含正式草稿、恢复与显式 `to-spec`）写入前，按 `.template-spec/plan/entry-review.md` 持久化审阅包并运行 `node scripts/verify-plan-spec-entry <state.yaml>`。检查默认 pending，缺项、过期或无真实回复即阻断；独立调研可继续。
 
 ## 结果与暂停
 
-咨询直接回答；工作单元留证并展示当前决定。
-
-结果包含：模式、仓库身份、阶段/工作单元、影响面、资产/门禁/Ticket/Slice/合同状态、证据及新鲜度、`ready-for-agent`、阻塞、本轮动作、下一单元、暂停/继续理由、Ticket 同步和 Git checkpoint。
+结构化结果保留模式、仓库身份、阶段/工作单元、影响面、资产/门禁/Ticket/Slice/合同状态、证据新鲜度、就绪、阻塞、本轮动作、下一单元、暂停理由、Ticket 同步和 Git checkpoint；用户说明按中文写作规范呈现。
 
-暂停会签时追加门禁 ID、`role_id`、`runtime_id`、会签文件路径、推荐答案和恢复动作；恢复前运行适用验证器。只有同一候选快照通过全部适用审查轴与 fresh verification，才能提出合并、发布或完成结论；发布仍须生物人决定。
+会签记录保留门禁 ID、`role_id`、`runtime_id`、文件路径、推荐答案和恢复动作；用户提示解释待决定事项与责任方。恢复前运行适用验证器。同一候选通过适用审查与 fresh verification 才可提出完成、合并或发布结论；发布仍须生物人决定。
 
 Plan / Spec / Design 追踪按 `.template-spec/process/stage-tracking.md`。
 
@@ -102,3 +96,5 @@ Spec 起草业务票，Design 校准后正式化；无设计影响直接正式
 ## 功能资产整理
 
 整理与旧票迁移先读 `.template-spec/process/feature-assets.md`，只按显式候选计划处理，保留状态、批准依据和原文；不得推进阶段。临时输入与草稿放临时工作区，引用后按正式资产保留。
+
+既有 YSS 实例的模板版本升级、旧治理布局迁移或升级恢复路由到 `yss-harness-upgrade`，按 `.template-spec/process/harness-upgrade.md` 执行；不由升级动作推进产品阶段或重写历史批准。

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

@@ -38,6 +38,9 @@ Plan 成功标准在既有 `success_criteria[].statement` 细化指标定义、
 
 ## 控制面引用
 
+- 新建领域战略、阶段决策包使用 JSON；存量 YAML 保持只读兼容，显式迁移见 `.template-spec/process/structured-assets.md`。使用 `scripts/contract plan-write/apply-write` 结构化落盘，不对合同作字符串拼接。校验器必须执行权威 Schema 后再检查跨文件语义。
+- 复用 Plan 原始决定编号，不自行重排；批准前用 `scripts/check-plan-stage-coverage` 生成绑定 Plan、决定记录和阶段包摘要的逐项对照证据，非目标使用显式映射。无法提取、缺项或映射歧义必须补齐；语义等价仍由独立评审确认，覆盖检查不构成批准。
+
 - 用户决定遵循 [用户决定协议](../yss-product-lifecycle/references/user-decisions.md)：决定必须绑定资产、版本、范围和证据；范围、风险、摘要或失效条件变化后重新确认。
 - checkpoint 是唯一机器状态源，业务 Ticket 只保存追踪引用，不复制阶段状态。
 - 每次批准、重发和消费者流转前执行 `context_reconciliation`，核验 `CONTEXT.md` 的全文与引用术语双摘要。

package/template/.agents/skills/yss-stage-decision/scripts/validate-domain-strategy.mjs

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertAssetTransactionIdle, assertCurrentAssetReference } from "../../../../scripts/lib/asset-transactions.mjs";
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecord } from "../../../../scripts/lib/approval-record.mjs";
 import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.mjs";
+import { parseAsset, validateAssetStructure } from '../../../../scripts/lib/structured-assets.mjs';
 
 import { extractTraceability } from "../../../../scripts/lib/strategic-handoff-rules.mjs";
 
@@ -49,6 +52,7 @@ function requireArray(object, field, path, errors, min = 0, itemKind = "string")
 }
 
 function validate(data, contextRoot) {
+  validateAssetStructure(data, 'domain-strategy');
   const errors = [];
   if (data?.traceability_version !== undefined) { try { extractTraceability(data); } catch(error) { errors.push(error.message); } }
   if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
@@ -210,11 +214,11 @@ const file = positionals[0];
 if (!file) fail(["用法: validate-domain-strategy.mjs <contract.yaml> [--root <project-root>]"]);
 else {
   try {
+    assertAssetTransactionIdle(values.root);
+    assertCurrentAssetReference(values.root, path.relative(path.resolve(values.root), path.resolve(file)));
     const source = await readFile(file, "utf8");
-    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
-    if (document.errors.length) fail([document.errors[0].message]);
-    else {
-      const errors = validate(document.toJS({ maxAliasCount: 0 }), values.root);
+    {
+      const errors = validate(parseAsset(source, file), values.root);
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }

package/template/.agents/skills/yss-stage-decision/scripts/validate-stage-decision-package.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertAssetTransactionIdle, assertCurrentAssetReference } from "../../../../scripts/lib/asset-transactions.mjs";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import process from "node:process";
@@ -7,6 +9,7 @@ import { parseArgs } from "node:util";
 import { parseDocument } from "../../../../scripts/vendor/yaml.mjs";
 import { loadApprovalRecord, resolveApprovalRef, validateApprovalRecord } from "../../../../scripts/lib/approval-record.mjs";
 import { verifyContextSnapshot } from "../../../../scripts/lib/context-contract.mjs";
+import { parseAsset, validateAssetStructure } from '../../../../scripts/lib/structured-assets.mjs';
 
 const required = ["schema_version", "stage_decision_id", "package_version", "status", "problem_statement", "target_users", "mvp", "non_goals", "success_criteria", "test_seams", "confirmed_decisions", "assumptions", "constraints", "unresolved_items", "context_snapshot", "domain_strategy_ref", "impact_assessment", "downstream_mapping", "evidence_refs", "approval"];
 const idPattern = /^stage-decision\.[a-z0-9][a-z0-9-]*$/;
@@ -25,6 +28,7 @@ function canonical(value) { if (Array.isArray(value)) return value.map(canonical
 function digest(value) { return `sha256:${createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex")}`; }
 
 async function validate(data, contextRoot) {
+  validateAssetStructure(data, 'stage-decision-package');
   const errors = [];
   if (!data || typeof data !== "object" || Array.isArray(data)) return ["合同必须是对象"];
   if (data.schema_version === 1) return ["migration-required: stage decision package v1 必须迁移到 v2 context_snapshot"];
@@ -143,11 +147,11 @@ const file = positionals[0];
 if (!file) fail(["用法: validate-stage-decision-package.mjs <package.yaml> [--root <project-root>]"]);
 else {
   try {
+    assertAssetTransactionIdle(values.root);
+    assertCurrentAssetReference(values.root, path.relative(path.resolve(values.root), path.resolve(file)));
     const source = await readFile(file, "utf8");
-    const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
-    if (document.errors.length) fail([document.errors[0].message]);
-    else {
-      const errors = await validate(document.toJS({ maxAliasCount: 0 }), values.root);
+    {
+      const errors = await validate(parseAsset(source, file), values.root);
       if (errors.length) fail(errors);
       else process.stdout.write(JSON.stringify({ result: "completed", contract: file }, null, 2) + "\n");
     }