create-yss-spec 3.5.4 → 3.5.6

package/vendor/cli-core/io.mjs

@@ -0,0 +1,153 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+export const hash = (b) => createHash("sha256").update(b).digest("hex");
+export const json = (x) => JSON.stringify(x, null, 2) + "\n";
+export function ensure(ok, message, code = "INVALID") {
+  if (!ok) throw Object.assign(new Error(message), { code });
+}
+export function stat(p) {
+  try {
+    return fs.lstatSync(p);
+  } catch (e) {
+    if (e.code === "ENOENT") return null;
+    throw e;
+  }
+}
+export function relative(ref) {
+  ensure(
+    typeof ref === "string" &&
+      ref.length > 0 &&
+      !ref.includes("\\") &&
+      !/[\x00-\x1f\x7f:]/.test(ref) &&
+      !path.posix.isAbsolute(ref) &&
+      ref.split("/").every((x) => x && x !== "." && x !== ".."),
+    `非法路径: ${ref}`,
+    "PATH",
+  );
+  return ref;
+}
+export function safe(root, ref) {
+  relative(ref);
+  let cursor = root;
+  const parts = ref.split("/");
+  for (let i = 0; i < parts.length; i++) {
+    cursor = path.join(cursor, parts[i]);
+    const s = stat(cursor);
+    ensure(!s?.isSymbolicLink(), `路径不允许符号链接: ${ref}`, "PATH");
+    if (i < parts.length - 1)
+      ensure(!s || s.isDirectory(), `父路径不是目录: ${ref}`, "PATH");
+  }
+  return cursor;
+}
+export function targetPath(p) {
+  const resolved = path.resolve(p);
+  let cursor = path.parse(resolved).root;
+  for (const part of resolved.slice(cursor.length).split("/").filter(Boolean)) {
+    cursor = path.join(cursor, part);
+    const s = stat(cursor);
+    ensure(
+      !s || (!s.isSymbolicLink() && s.isDirectory()),
+      `目标路径不是普通目录: ${cursor}`,
+      "PATH",
+    );
+  }
+  return resolved;
+}
+const protectedRoots = new Set([
+  ".git",
+  ".gitmodules",
+  "node_modules",
+  "src",
+  "app",
+  "apps",
+  "backend",
+  "frontend",
+  "target",
+  "dist",
+  "build",
+  "deploy",
+  "Dockerfile",
+  "docker-compose.yml",
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+  "pom.xml",
+  "mvnw",
+  "mvnw.cmd",
+  ".mvn",
+  "gradlew",
+  "gradlew.bat",
+  "build.gradle",
+  "settings.gradle",
+  ".github",
+  ".yss-harness-state",
+]);
+export function governance(ref) {
+  relative(ref);
+  ensure(
+    !protectedRoots.has(ref.split("/")[0]) && !ref.split("/").includes(".git"),
+    `受保护业务/Git/状态路径: ${ref}`,
+    "PROTECTED",
+  );
+  ensure(
+    /^(?:\.(?:agents|claude|codex|cursor|pi|qoder|trae)\/|\.template-spec\/|docs\/|scripts\/)/.test(
+      ref,
+    ) ||
+      [
+        ".cursorrules",
+        ".gitignore",
+        ".nvmrc",
+        "AGENTS.md",
+        "CLAUDE.md",
+        "CONTEXT.md",
+        "README.md",
+        "DESIGN.md",
+        "skills-lock.json",
+        "yss-project.yaml",
+        "yss-public-skills.json",
+      ].includes(ref),
+    `不在治理边界: ${ref}`,
+    "PROTECTED",
+  );
+  ensure(
+    ref !== "scripts/instantiate-harness",
+    `旧创建入口不得分发`,
+    "PROTECTED",
+  );
+}
+export function descriptor(root, ref) {
+  const file = safe(root, ref),
+    s = stat(file);
+  if (!s) return null;
+  ensure(
+    s.isFile() && s.nlink === 1,
+    `目标必须是非硬链接普通文件: ${ref}`,
+    "PATH",
+  );
+  return {
+    type: "file",
+    digest: hash(fs.readFileSync(file)),
+    mode: s.mode & 0o777,
+  };
+}
+export function same(a, b) {
+  return (
+    (a === null && b === null) ||
+    Boolean(
+      a && b && a.type === b.type && a.digest === b.digest && a.mode === b.mode,
+    )
+  );
+}
+export function write(root, ref, bytes, mode = 0o644) {
+  const file = safe(root, ref);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, bytes);
+  fs.chmodSync(file, mode);
+}
+export function readJson(root, ref) {
+  return JSON.parse(fs.readFileSync(safe(root, ref), "utf8"));
+}

package/vendor/cli-core/layout-migration.mjs

@@ -0,0 +1,64 @@
+import * as fs from "node:fs";
+import { descriptor, ensure, hash, safe, same } from "./io.mjs";
+
+const oldDirs = [
+  "docs/agents", "docs/process", "docs/templates", "docs/user-guide",
+  "docs/plan/templates", "docs/api/templates", "docs/architecture/templates",
+  "docs/design/templates", "docs/design/tokens", "docs/design/schemas",
+  "docs/design/diagrams", "docs/discovery/templates",
+];
+const oldFiles = [
+  "docs/adr/README.md", "docs/architecture/README.md",
+  "docs/plan/README.md", "docs/plan/entry-review.md",
+  "docs/discovery/README.md", "docs/discovery/IDEATION.md",
+  "docs/design/README.md", "docs/design/design.md",
+  "docs/design/design-system-sync.yaml", "docs/design/preview.html",
+  "docs/design/preview-dark.html", "docs/design/preview.css",
+  "docs/design/preview.js", "docs/engineering/backend-platforms.json",
+  "docs/engineering/backend-platforms.md",
+];
+const trackerFrom = "docs/agents/issue-tracker.md";
+const trackerTo = ".template-spec/agents/issue-tracker.md";
+
+function collect(target) {
+  const found = new Set();
+  function visit(ref) {
+    const file = safe(target, ref);
+    let entry;
+    try { entry = fs.lstatSync(file); }
+    catch (error) { if (error.code === "ENOENT") return; throw error; }
+    ensure(!entry.isSymbolicLink(), `旧治理路径为符号链接: ${ref}`, "PATH");
+    if (entry.isFile()) { found.add(ref); return; }
+    ensure(entry.isDirectory(), `旧治理路径不是普通文件或目录: ${ref}`, "PATH");
+    for (const name of fs.readdirSync(file)) {
+      if (name !== ".DS_Store") visit(`${ref}/${name}`);
+    }
+  }
+  for (const ref of [...oldDirs, ...oldFiles]) visit(ref);
+  return [...found].sort();
+}
+
+export function prepareLayoutMigration(target, meta, files, opts) {
+  const legacyFiles = collect(target);
+  if (!legacyFiles.length) return { legacyFiles, replacements: new Map(), deletions: [] };
+  ensure(opts.command !== "diff" && opts.migrateLayout, `旧治理目录需显式 --migrate-layout: ${legacyFiles.join(", ")}`, "LAYOUT");
+  const replacements = new Map();
+  const deletions = [];
+  for (const from of legacyFiles) {
+    const to = `.template-spec/${from.slice("docs/".length)}`;
+    const before = descriptor(target, from);
+    const destination = descriptor(target, to);
+    if (from === trackerFrom) {
+      ensure(files.has(trackerTo), `当前模板缺少 tracker 目标: ${trackerTo}`, "LAYOUT");
+      const bytes = fs.readFileSync(safe(target, from));
+      ensure(!destination || destination.digest === hash(bytes), `项目 tracker 新旧配置不一致: ${from}`, "LAYOUT");
+      if (!destination) replacements.set(to, bytes);
+    } else {
+      const baseline = meta?.managedFiles?.[from]?.baseline;
+      ensure(baseline && same(before, baseline), `旧治理文件缺少可信基线或已修改: ${from}`, "LAYOUT");
+      ensure(files.has(to) || !destination, `目标路径已有文件且当前模板未分发: ${to}`, "LAYOUT");
+    }
+    deletions.push({ path: from, before, after: null });
+  }
+  return { legacyFiles, replacements, deletions };
+}

package/vendor/cli-core/legacy.mjs

@@ -0,0 +1,19 @@
+import { ensure, governance } from './io.mjs';
+import { userOwned } from './family.mjs';
+export function normalizeLegacy(meta, family) {
+  ensure(family.side === 'design' && meta.metadataSchemaVersion === 1, '不支持旧实例', 'LEGACY');
+  for (const key of ['profileId', 'templateName', 'templateSource']) ensure(meta[key] === family[key], `旧 metadata 身份矛盾: ${key}`, 'IDENTITY');
+  ensure(/^[a-f0-9]{40}$/.test(meta.templateCommit) && /^[a-f0-9]{64}$/.test(meta.snapshotHash) && /^[a-f0-9]{64}$/.test(meta.managedFilesManifestVersion), '旧 metadata 来源摘要不完整', 'BASELINE');
+  ensure(['committed', 'working-tree'].includes(meta.templateSourceState), '旧 metadata 来源状态非法', 'BASELINE');
+  ensure(meta.variables && ['projectName','businessDomain','teamSize','issueTracker'].every(k => typeof meta.variables[k] === 'string' && meta.variables[k].trim()) && ['local-markdown','github','gitlab'].includes(meta.variables.issueTracker), '旧实例变量不完整', 'BASELINE');
+  ensure(meta.managedFiles && typeof meta.managedFiles === 'object' && !Array.isArray(meta.managedFiles), '旧基线缺失', 'BASELINE');
+  const managedFiles = {}, legacyRetainedFiles = [];
+  for (const [ref, record] of Object.entries(meta.managedFiles)) {
+    if (ref !== "scripts/instantiate-harness") governance(ref);
+    ensure(record && ['copy','render'].includes(record.type) && /^[a-f0-9]{64}$/.test(record.contentHash), `旧基线非法: ${ref}`, 'BASELINE');
+    if (ref === "scripts/instantiate-harness") { legacyRetainedFiles.push(ref); continue; }
+    if (!userOwned(ref, family)) managedFiles[ref] = { baseline: {type:'file',digest:record.contentHash,mode:0o644}, lastApplied:null, legacyUnproven:true };
+  }
+  for (const ref of ['yss-project.yaml','.template-spec/process/harness-profile.yaml','AGENTS.md','CONTEXT.md']) ensure(managedFiles[ref], `旧基线缺少合同: ${ref}`, 'BASELINE');
+  return {...meta, legacy:true, legacyRetainedFiles, variables:{...meta.variables,includeExampleDocs:true}, managedFiles};
+}

package/vendor/cli-core/migrate.mjs

@@ -0,0 +1,237 @@
+// Public migration driver. Adapters only prepare candidates; this module owns writes.
+import * as fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {spawnSync} from 'node:child_process';
+import {hash,json,ensure,stat,safe,descriptor,same,write,targetPath,governance} from './io.mjs';
+import {guardNestedRepository,gitlinks,METADATA} from './identity.mjs';
+import {applyTransaction,inspectState,recoveryPreview,recover as recoverTransaction} from './transaction.mjs';
+
+const INDEX='.yss-harness-state/upgrade.json';
+export function assertUpgradeVersion(from,to) {
+  const parts=v=>{
+    if(typeof v!=='string')return null;
+    const match=v.match(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/);
+    if(!match)return null;
+    const pre=match[4]?.split('.') || [];
+    if(pre.some(x=>/^\d+$/.test(x) && x.length>1 && x[0]==='0'))return null;
+    return {numbers:match.slice(1,4).map(BigInt),pre};
+  };
+  const a=parts(from),b=parts(to);ensure(a && b,'缺少可比较的 CLI 版本基线','VERSION');
+  let order=0;
+  for(let i=0;i<3 && !order;i++)order=b.numbers[i]>a.numbers[i]?1:b.numbers[i]<a.numbers[i]?-1:0;
+  if(!order && (!a.pre.length || !b.pre.length))order=b.pre.length?-1:a.pre.length?1:0;
+  else if(!order)for(let i=0;i<Math.max(a.pre.length,b.pre.length) && !order;i++){
+    const x=a.pre[i],y=b.pre[i];
+    if(x===undefined)order=1;else if(y===undefined)order=-1;
+    else if(x!==y){const xn=/^\d+$/.test(x),yn=/^\d+$/.test(y);order=xn&&yn?(BigInt(y)>BigInt(x)?1:-1):xn!==yn?(xn?1:-1):(y>x?1:-1);}
+  }
+  ensure(order>=0,'migrate 不支持 CLI 降级','VERSION');
+}
+const OMIT=new Set(['.git','node_modules','.codegraph','.graphify','__pycache__','.DS_Store']);
+export function inventory(root, prefix='', out={}) {
+  for(const name of fs.readdirSync(safeDirectory(root,prefix)).sort()) {
+    if(OMIT.has(name) || !prefix && name==='.yss-harness-state') continue;
+    const ref=prefix?`${prefix}/${name}`:name, p=path.join(root,ref), s=fs.lstatSync(p);
+    if(s.isSymbolicLink()) out[ref]={type:'symlink',link:fs.readlinkSync(p)};
+    else if(s.isDirectory()) {out[ref]={type:'directory',mode:s.mode&0o777};inventory(root,ref,out);}
+    else {ensure(s.isFile() && s.nlink===1,`不支持特殊文件/硬链接: ${ref}`,'PATH');out[ref]=descriptor(root,ref);}
+  }
+  return out;
+}
+function safeDirectory(root,ref) {return ref?safe(root,ref):root;}
+export function copyCandidate(root,destination,tree=inventory(root)) {
+  for(const [ref,d] of Object.entries(tree)) {
+    const p=path.join(destination,ref);fs.mkdirSync(path.dirname(p),{recursive:true});
+    if(d.type==='directory') fs.mkdirSync(p,{recursive:true,mode:d.mode});
+    else if(d.type==='symlink') fs.symlinkSync(d.link,p);
+    else {fs.copyFileSync(safe(root,ref),p);fs.chmodSync(p,d.mode);}
+  }
+}
+const digest=value=>hash(JSON.stringify(value));
+function gitStamp(root) {
+  const r=spawnSync('git',['--no-optional-locks','-c','core.fsmonitor=false','-C',root,'ls-files','--stage','-z'],{encoding:'buffer',maxBuffer:32*1024*1024});
+  const head=spawnSync('git',['--no-optional-locks','-C',root,'rev-parse','HEAD'],{encoding:'utf8'});
+  return {index:r.status===0?hash(r.stdout):null,head:head.status===0?head.stdout.trim():null,links:gitlinks(root)};
+}
+function outside(root,p) {
+  ensure(typeof p==='string' && path.isAbsolute(p),'计划与归档路径必须是绝对路径','PATH');
+  const result=path.resolve(p);targetPath(path.dirname(result));
+  ensure(result!==root && !result.startsWith(root+path.sep) && !root.startsWith(result+path.sep),'计划/归档必须位于项目外','PATH');
+  ensure(!stat(result)?.isSymbolicLink(),'外部路径不能是符号链接','PATH');return result;
+}
+function durable(root,ref,bytes,mode=0o600) {
+  const p=safe(root,ref);fs.mkdirSync(path.dirname(p),{recursive:true});
+  const temp=p+'.writing-'+randomUUID();
+  const fd=fs.openSync(temp,'wx',mode);
+  try{fs.writeFileSync(fd,bytes);fs.fsyncSync(fd);}finally{fs.closeSync(fd);}
+  fs.renameSync(temp,p);
+  const dir=fs.openSync(path.dirname(p),'r');try{fs.fsyncSync(dir);}finally{fs.closeSync(dir);}
+}
+function readFile(p){ensure(stat(p)?.isFile() && !stat(p).isSymbolicLink() && stat(p).nlink===1,`不是普通文件: ${p}`,'PATH');return fs.readFileSync(p);}
+function guard(root,adapter,ref) {
+  if(ref!==adapter.family.metadataFile) governance(ref);
+  ensure(ref!==INDEX,'不能迁移事务状态','PROTECTED');
+  guardNestedRepository(root,ref);
+  ensure(!gitlinks(root).some(p=>ref===p || ref.startsWith(p+'/')),`受保护 gitlink: ${ref}`,'PROTECTED');
+  descriptor(root,ref);
+}
+function encode(operations) {return operations.map(op=>({path:op.path,before:op.before,after:op.after,...(op.after?{contentBase64:op.bytes.toString('base64')}:{})}));}
+function validateOperations(root,adapter,ops) {
+  ensure(Array.isArray(ops),'操作列表非法','PLAN');const paths=new Set();
+  for(const op of ops){guard(root,adapter,op.path);ensure(!paths.has(op.path),'重复迁移路径','PLAN');paths.add(op.path);
+    for(const d of [op.before,op.after]) ensure(d===null || d?.type==='file' && /^[a-f0-9]{64}$/.test(d.digest) && Number.isInteger(d.mode) && d.mode>=0 && d.mode<=0o777,'文件描述非法','PLAN');
+    if(op.after) ensure(typeof op.contentBase64==='string' && hash(Buffer.from(op.contentBase64,'base64'))===op.after.digest,'候选内容摘要错误','PLAN');
+  }
+}
+function assertExecutor(adapter,plan) {ensure(plan.schemaVersion===1 && plan.family===adapter.family.packageName && plan.executor===adapter.fingerprint,'CLI 家族/执行器与计划不一致','EXECUTOR');}
+function checkPlan(adapter,plan) {
+  const {planDigest,...body}=plan;ensure(planDigest===digest(body),'计划摘要错误','PLAN');assertExecutor(adapter,plan);
+  targetPath(plan.target);ensure(fs.realpathSync(plan.target)===plan.target,'项目实际路径已变化','PATH');
+  ensure(/^[a-f0-9-]{36}$/.test(plan.id) && !Number.isNaN(Date.parse(plan.createdAt)),'计划身份非法','PLAN');
+  outside(plan.target,plan.archive);validateOperations(plan.target,adapter,plan.operations);
+}
+function index(root,adapter) {
+  if(!stat(safe(root,INDEX)))return {schemaVersion:1,family:adapter.family.packageName,runs:[]};
+  const value=JSON.parse(readFile(safe(root,INDEX)));
+  ensure(value.schemaVersion===1 && value.family===adapter.family.packageName && Array.isArray(value.runs),'迁移索引身份不一致','STATE');return value;
+}
+function state(root,adapter) {
+  if(!stat(safe(root,'.yss-harness-state')))return {pending:[]};
+  return inspectState(root,adapter.family);
+}
+function lock(root,fn) {
+  const file=safe(root,'.yss-harness-migrate.lock');
+  if(stat(file)) {
+    const owner=JSON.parse(readFile(file));ensure(owner.host===os.hostname() && Number.isInteger(owner.pid) && owner.pid>0,'无法判断迁移锁持有者','LOCKED');
+    let alive=true;try{process.kill(owner.pid,0);}catch(e){if(e.code==='ESRCH')alive=false;else throw e;}
+    ensure(!alive,'另一个迁移正在运行','LOCKED');fs.unlinkSync(file);
+  }
+  const fd=fs.openSync(file,'wx',0o600);fs.writeFileSync(fd,json({pid:process.pid,host:os.hostname()}));fs.fsyncSync(fd);fs.closeSync(fd);
+  try{return fn();}finally{fs.unlinkSync(file);}
+}
+function observed(root) {const tree=inventory(root);delete tree['.yss-harness-migrate.lock'];return tree;}
+function currentMatches(root,plan) {ensure(digest(observed(root))===digest(plan.inputs) && digest(gitStamp(root))===digest(plan.git),'计划后项目或 Git 输入已变化，请重新规划','STALE_PLAN');}
+function record(root,idx,run,phase) {run.phase=phase;durable(root,INDEX,json(idx));durable(run.archive,'receipt.json',json(run));}
+function loadArchived(root,adapter,run) {
+  outside(root,run.archive);targetPath(run.archive);
+  const plan=JSON.parse(readFile(safe(run.archive,'plan.json')));checkPlan(adapter,plan);
+  ensure(plan.id===run.id && plan.planDigest===run.planDigest && plan.target===root && plan.archive===run.archive,'归档与回执不一致','STATE');
+  const journalRef=safe(root,`.yss-harness-state/${adapter.family.side}/transactions/${plan.id}/journal.json`);
+  if(stat(journalRef)){const journal=JSON.parse(readFile(journalRef));const shape=ops=>ops.map(({path,before,after})=>({path,before,after}));ensure(journal.id===plan.id && journal.profileId===adapter.family.profileId && digest(shape(journal.operations))===digest(shape(plan.operations)),'归档操作与原事务不一致','ARCHIVE');}
+  else ensure(run.phase==='applying','原事务日志缺失','STATE');
+  return plan;
+}
+function afterMatches(root,operations) {for(const op of operations)ensure(same(descriptor(root,op.path),op.after),`升级后已有修改: ${op.path}`,'CONCURRENT');}
+function unchangedInputs(root,plan) {
+  const changed=new Set(plan.operations.map(o=>o.path));
+  const select=tree=>Object.fromEntries(Object.entries(tree).filter(([ref,d])=>!changed.has(ref) && !(d.type==='directory' && [...changed].some(p=>p.startsWith(ref+'/')))));
+  ensure(digest(select(observed(root)))===digest(select(plan.inputs)) && digest(gitStamp(root))===digest(plan.git),'迁移期间未写入资产或 Git 状态变化','CONCURRENT');
+}
+function archivedBefore(plan) {
+  return plan.operations.map((op,i)=>{
+    let bytes;
+    if(op.before){bytes=readFile(safe(plan.archive,`before/${i}`));ensure(hash(bytes)===op.before.digest,'备份摘要损坏','ARCHIVE');}
+    return {path:op.path,before:op.after,after:op.before,bytes};
+  });
+}
+function closeInterrupted(root,adapter,idx) {
+  const pending=state(root,adapter);
+  const validate=()=>{targetPath(root);ensure(!METADATA.some(ref=>ref!==adapter.family.metadataFile && stat(safe(root,ref))),'异族身份禁止恢复','IDENTITY');};
+  validate();
+  if(pending.pending.length)recoverTransaction(root,adapter.family,pending,validate);
+  for(const run of idx.runs.filter(r=>['applying','rolling-back'].includes(r.phase))) {
+    const plan=loadArchived(root,adapter,run);
+    const journalPath=safe(root,`.yss-harness-state/${adapter.family.side}/transactions/${run.phase==='rolling-back'?run.rollbackId:run.id}/journal.json`);
+    const journal=stat(journalPath)?JSON.parse(readFile(journalPath)):null;
+    const succeeded=journal?.phase==='committed';
+    if(succeeded)afterMatches(root,run.phase==='rolling-back'?plan.operations.map(o=>({...o,after:o.before})):plan.operations);
+    record(root,idx,run,run.phase==='rolling-back'?(succeeded?'rolled-back':'applied'):(succeeded?'applied':'recovered'));
+  }
+}
+export function migration(adapter,command,opts={}) {
+  let plan;
+  if(command==='apply'){ensure(opts.plan,'apply 需要 --plan','ARGS');plan=JSON.parse(readFile(path.resolve(opts.plan)));checkPlan(adapter,plan);}
+  const root=targetPath(opts.targetDir || plan?.target || process.cwd());
+  ensure(stat(root)?.isDirectory(),'项目目录不存在','PATH');
+  ensure(!plan || plan.target===root,'计划与目标目录不一致','IDENTITY');
+  if(command==='plan') {
+    adapter.check(root,opts);
+    ensure(!state(root,adapter).pending.length && !index(root,adapter).runs.some(r=>['applying','rolling-back'].includes(r.phase)),'请先 recover 未完成迁移','INTERRUPTED');
+    const output=outside(root,path.resolve(opts.output || ''));
+    ensure(opts.output && !stat(output),'--output 必须是项目外全新文件','PATH');
+    const inputs=observed(root), git=gitStamp(root), id=randomUUID(),createdAt=new Date().toISOString();
+    const archive=outside(root,path.resolve(opts.archiveDir || path.join(os.homedir(),'.yss-harness/archives',hash(root+'\0'+adapter.family.packageName),id)));
+    ensure(!stat(archive),'归档目录必须全新','ARCHIVE');
+    const resolutions=opts.resolutions?JSON.parse(readFile(path.resolve(opts.resolutions))):{};
+    ensure(resolutions && typeof resolutions==='object' && !Array.isArray(resolutions),'冲突决议必须为路径映射','PLAN');
+    const settings={prune:Boolean(opts.prune),migrateLayout:Boolean(opts.migrateLayout),resolutions};
+    let prepared;try{prepared=adapter.prepare(root,settings,id,createdAt);}catch(e){if(e.code==='CONFLICT' || e.result?.conflicts?.length)e.result={...e.result,status:'blocked'};throw e;}
+    const operations=encode(prepared.operations);validateOperations(root,adapter,operations);
+    const body={schemaVersion:1,id,createdAt,target:root,family:adapter.family.packageName,executor:adapter.fingerprint,template:adapter.template,archive,settings,inputs,git,operations,changes:prepared.changes || [],rules:['managed-sync.v1',...(settings.migrateLayout?['layout-migration.v1']:[]),...(settings.prune?['retirement.v1']:[])]};
+    plan={...body,planDigest:digest(body)};currentMatches(root,plan);
+    durable(path.dirname(output),path.basename(output),json(plan));
+    return {schemaVersion:1,command:'migrate plan',status:'planned',target:root,plan:output,planDigest:plan.planDigest,changes:plan.changes,operations:operations.length,archive};
+  }
+  const idx=index(root,adapter);
+  if(command==='status'){adapter.check(root,{migrateLayout:true});return {schemaVersion:1,command:'migrate status',status:'ok',target:root,transactions:idx.runs,pending:state(root,adapter).pending.map(x=>x.journal.id)};}
+  if(command==='recover') {
+    // Preview uses existing journal validation, including drift and archive checks, without creating state.
+    const pending=state(root,adapter);recoveryPreview(root,adapter.family,pending);for(const run of idx.runs.filter(r=>['applying','rolling-back'].includes(r.phase))){const p=loadArchived(root,adapter,run);archivedBefore(p);}
+    if(!opts.apply)return {schemaVersion:1,status:'preview',target:root,transactions:idx.runs.filter(r=>['applying','rolling-back'].includes(r.phase)),pending:pending.pending.map(x=>x.journal.id)};
+    return lock(root,()=>{closeInterrupted(root,adapter,idx);return {schemaVersion:1,status:'recovered',target:root,transactions:idx.runs};});
+  }
+  ensure(['apply','rollback'].includes(command),'未知 migrate 子命令','ARGS');
+  if(command==='rollback' && !opts.apply) {
+    ensure(!state(root,adapter).pending.length,'请先 recover 未完成事务','INTERRUPTED');
+    const run=idx.runs.at(-1);ensure(run?.phase==='applied','没有可回退的最近成功迁移','STATE');
+    const p=loadArchived(root,adapter,run);afterMatches(root,p.operations);const inverse=archivedBefore(p);
+    return {schemaVersion:1,status:'preview',target:root,id:run.id,paths:inverse.map(o=>o.path)};
+  }
+  return lock(root,()=>{
+    ensure(!state(root,adapter).pending.length && !idx.runs.some(r=>['applying','rolling-back'].includes(r.phase)),'请先 recover 未完成迁移','INTERRUPTED');
+    if(command==='rollback') {
+      const run=idx.runs.at(-1);ensure(run?.phase==='applied','没有可回退的最近成功迁移','STATE');
+      plan=loadArchived(root,adapter,run);afterMatches(root,plan.operations);const inverse=archivedBefore(plan);
+      if(!opts.apply)return {schemaVersion:1,status:'preview',target:root,id:run.id,paths:inverse.map(o=>o.path)};
+      run.rollbackId=randomUUID();record(root,idx,run,'rolling-back');
+      try{applyTransaction(root,adapter.family,inverse,op=>{if(op)guard(root,adapter,op.path);},run.rollbackId,false,()=>afterMatches(root,inverse));record(root,idx,run,'rolled-back');}
+      catch(e){closeInterrupted(root,adapter,idx);throw e;}
+      return {schemaVersion:1,status:'rolled-back',target:root,id:run.id,archive:run.archive};
+    }
+    const existing=idx.runs.find(r=>r.id===plan.id);
+    if(existing){ensure(existing.phase==='applied' && existing.planDigest===plan.planDigest,'计划已执行或恢复，请重新规划','STATE');afterMatches(root,plan.operations);return {schemaVersion:1,status:'applied',target:root,reused:true,...existing};}
+    adapter.check(root,plan.settings);currentMatches(root,plan);
+    // Regenerate from the fixed executable and explicit resolutions: edited plans cannot add arbitrary writes.
+    const rebuilt=encode(adapter.prepare(root,plan.settings,plan.id,plan.createdAt).operations);
+    ensure(digest(rebuilt)===digest(plan.operations),'计划内容与固定执行器重新生成的结果不一致','PLAN');currentMatches(root,plan);
+    if(!plan.operations.length)return {schemaVersion:1,status:'unchanged',target:root};
+    ensure(!stat(plan.archive),'归档目录已存在','ARCHIVE');fs.mkdirSync(plan.archive,{recursive:true,mode:0o700});
+    durable(plan.archive,'plan.json',json(plan));
+    for(const [i,op]of plan.operations.entries())if(op.before){const bytes=readFile(safe(root,op.path));ensure(hash(bytes)===op.before.digest,'备份期间输入变化','CONCURRENT');durable(plan.archive,`before/${i}`,bytes,op.before.mode);}
+    if(plan.settings.migrateLayout || plan.settings.prune || Object.keys(plan.settings.resolutions).length)copyCandidate(root,path.join(plan.archive,'project-copy'),plan.inputs);
+    archivedBefore(plan);currentMatches(root,plan);
+    // applyTransaction owns its durable WAL. Create its state before writing our receipt index.
+    if(!stat(safe(root,'.yss-harness-state'))) {
+      fs.mkdirSync(safe(root,`.yss-harness-state/${adapter.family.side}/transactions`),{recursive:true});
+      durable(root,'.yss-harness-state/owner.json',json({schemaVersion:1,profileId:adapter.family.profileId}));
+    }
+    const run={schemaVersion:1,id:plan.id,planDigest:plan.planDigest,archive:plan.archive,family:plan.family,createdAt:plan.createdAt,template:plan.template,executor:plan.executor,phase:'applying'};idx.runs.push(run);record(root,idx,run,'applying');
+    try {
+      const ops=plan.operations.map(op=>({...op,bytes:op.after?Buffer.from(op.contentBase64,'base64'):undefined}));
+      applyTransaction(root,adapter.family,ops,op=>{if(op)guard(root,adapter,op.path);else unchangedInputs(root,plan);},plan.id,false,()=>{const checks=adapter.verify(root);afterMatches(root,plan.operations);unchangedInputs(root,plan);run.verification={status:'passed',checks:checks || [],completedAt:new Date().toISOString()};});
+      record(root,idx,run,'applied');
+    }catch(e){closeInterrupted(root,adapter,idx);throw e;}
+    return {schemaVersion:1,status:'applied',target:root,...run};
+  });
+}
+export function parseMigration(argv) {
+  const args=[...argv],command=args.shift() || 'status',opts={};
+  ensure(['plan','apply','status','recover','rollback'].includes(command),'migrate plan|apply|status|recover|rollback','ARGS');
+  const values={'--target-dir':'targetDir','--output':'output','--plan':'plan','--archive-dir':'archiveDir','--resolutions':'resolutions'};
+  const flags={'--apply':'apply','--prune':'prune','--migrate-layout':'migrateLayout','--json':'json'};
+  const allowed={plan:['targetDir','output','archiveDir','resolutions','prune','migrateLayout','json'],apply:['targetDir','plan','json'],status:['targetDir','json'],recover:['targetDir','apply','json'],rollback:['targetDir','apply','json']};
+  while(args.length){const flag=args.shift(),key=values[flag] || flags[flag];ensure(key && allowed[command].includes(key),`不适用的参数: ${flag}`,'ARGS');ensure(!(key in opts),`重复参数: ${flag}`,'ARGS');if(values[flag]){ensure(args.length && !args[0].startsWith('--'),`参数缺少值: ${flag}`,'ARGS');opts[key]=args.shift();}else opts[key]=true;}
+  return {command,opts};
+}

package/vendor/cli-core/migration-adapter.mjs

@@ -0,0 +1,19 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import {loadBundle} from './bundle.mjs';
+import {identity} from './identity.mjs';
+import {execute} from './engine.mjs';
+import {verifyInstance} from './verification.mjs';
+import {hash,ensure} from './io.mjs';
+import {migration,parseMigration,assertUpgradeVersion} from './migrate.mjs';
+export function dedicatedAdapter(packageRoot) {
+  const bundle=loadBundle(packageRoot);
+  const fingerprint=hash(JSON.stringify({pkg:bundle.pkg,snapshot:bundle.snapshot,core:bundle.core,driver:hash(fs.readFileSync(new URL('./migrate.mjs',import.meta.url)))}));
+  return {
+    family:bundle.family,fingerprint,template:{version:bundle.pkg.version,commit:bundle.snapshot.templateCommit,snapshotHash:bundle.snapshot.snapshotHash},
+    check(root,opts){ensure(root!==packageRoot && !root.startsWith(packageRoot+path.sep) && !packageRoot.startsWith(root+path.sep),'目标不得覆盖 CLI 安装目录','PATH');const meta=identity(root,bundle,'sync',opts.migrateLayout);ensure(meta,'migrate 仅接受已有同家族实例','IDENTITY');assertUpgradeVersion(meta.cliVersion,bundle.pkg.version);},
+    prepare(root,opts,id,time){return execute(bundle,root,{command:'sync',apply:true,prune:opts.prune,migrateLayout:opts.migrateLayout,migrationResolutions:opts.resolutions,migrationId:id,migrationTime:time,captureMigration:(operations,result)=>({operations,changes:result.changes})});},
+    verify(root){return verifyInstance(bundle,root);},
+  };
+}
+export function runMigration(packageRoot,args){const {command,opts}=parseMigration(args);return migration(dedicatedAdapter(packageRoot),command,opts);}

package/vendor/cli-core/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@yss-internal/dedicated-harness-cli-core",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=22 <27"
+  },
+  "packageManager": "pnpm@10.15.0",
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  }
+}

package/vendor/cli-core/scaffold.mjs

@@ -0,0 +1,117 @@
+// Maintainer entry: create only an empty thin CLI working directory.
+import * as fs from "node:fs";
+import path from "node:path";
+import { ensure, write, json, stat } from "./io.mjs";
+const [side, output] = process.argv.slice(2);
+ensure(
+  ["backend", "frontend"].includes(side) && output,
+  "usage: node scaffold.mjs backend|frontend <empty-directory>",
+);
+const root = path.resolve(output),
+  name = `create-yss-harness-${side}`;
+ensure(
+  !stat(root) || fs.readdirSync(root).length === 0,
+  "薄包目标必须不存在或为空",
+);
+write(
+  root,
+  "package.json",
+  json({
+    name,
+    version: "0.1.0",
+    description: `创建和同步 YSS ${side} 专职 Harness 治理项目`,
+    type: "module",
+    license: "UNLICENSED",
+    engines: { node: ">=22 <27" },
+    packageManager: "pnpm@10.15.0",
+    repository: {
+      type: "git",
+      url: `git+https://github.com/iloveZzz/${name}.git`,
+    },
+    bin: { [name]: `bin/${name}.js` },
+    files: [
+      "bin",
+      "config",
+      "vendor/cli-core",
+      "cli-core.lock.json",
+      "template",
+      "template.manifest.json",
+      "template.snapshot.json",
+    ],
+    scripts: {
+      "sync-core": "node scripts/sync-core.mjs",
+      "sync-template": "node scripts/sync-template.mjs",
+      "verify-bundle": "node scripts/verify-bundle.mjs",
+      test: "node --test tests/*.test.mjs",
+      prepack: "node scripts/verify-bundle.mjs",
+    },
+  }),
+);
+write(
+  root,
+  `bin/${name}.js`,
+  `#!/usr/bin/env node\nimport {fileURLToPath} from 'node:url';\nimport {main} from '../vendor/cli-core/cli.mjs';\nawait main(fileURLToPath(new URL('..',import.meta.url)));\n`,
+  0o755,
+);
+for (const kind of ["core", "template"])
+  write(
+    root,
+    `scripts/sync-${kind}.mjs`,
+    `import {fileURLToPath} from 'node:url';\nimport {sync${kind[0].toUpperCase() + kind.slice(1)}} from '../vendor/cli-core/build.mjs';\nconst args=process.argv.slice(2),check=args.includes('--check'),values=args.filter(x=>x!=='--check');\nif(values.length!==2)throw new Error('usage: pnpm sync-${kind} <source-repo> <commit> [--check]');\nconsole.log(JSON.stringify(sync${kind[0].toUpperCase() + kind.slice(1)}(values[0],values[1],fileURLToPath(new URL('..',import.meta.url)),check),null,2));\n`,
+  );
+write(
+  root,
+  "scripts/verify-bundle.mjs",
+  `import {fileURLToPath} from 'node:url';\nimport {verifyCore} from '../vendor/cli-core/build.mjs';\nimport {loadBundle} from '../vendor/cli-core/bundle.mjs';\nconst root=fileURLToPath(new URL('..',import.meta.url));\nconst core=verifyCore(root),bundle=loadBundle(root);\nconsole.log(JSON.stringify({package:bundle.pkg.name,core:core.digest,template:bundle.snapshot.snapshotHash,files:bundle.files.size}));\n`,
+);
+write(
+  root,
+  "tests/package.test.mjs",
+  `import {test} from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {spawnSync} from 'node:child_process';
+const root=fileURLToPath(new URL('..',import.meta.url));
+test('固定包契约、真实模板计划零写入和旧实例拒绝',t=>{
+ const scratch=fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(),'${name}-')));t.after(()=>fs.rmSync(scratch,{recursive:true,force:true}));
+ const target=path.join(scratch,'project');
+ const run=(...args)=>spawnSync(process.execPath,[path.join(root,'bin/${name}.js'),...args,'--json'],{encoding:'utf8',maxBuffer:32*1024*1024});
+ const verify=spawnSync(process.execPath,[path.join(root,'scripts/verify-bundle.mjs')],{encoding:'utf8'});assert.equal(verify.status,0,verify.stderr);
+ let r=run('init','--target-dir',target,'--project-name','验收实例','--dry-run');assert.equal(r.status,0,r.stderr);
+ const plan=JSON.parse(r.stdout);assert.equal(plan.status,'preview');assert.equal(fs.existsSync(target),false);
+ assert.ok(plan.changes.some(x=>x.path==='scripts/repository-mode'));assert.ok(plan.changes.some(x=>x.path==='.template-spec/process/harness-profile.yaml'));assert.ok(!plan.changes.some(x=>x.path==='scripts/instantiate-harness'));
+ fs.mkdirSync(target);const metadata=path.join(target,'.yss-harness-${side}.json');fs.writeFileSync(metadata,'{"schema_version":1}');
+ r=run('attach','--target-dir',target,'--apply','--force');assert.equal(r.status,1);assert.equal(JSON.parse(r.stdout).code,'LEGACY');assert.deepEqual(fs.readdirSync(target),['.yss-harness-${side}.json']);
+});
+`,
+);
+write(
+  root,
+  ".github/workflows/ci.yml",
+  `name: CLI\non: [push, pull_request, workflow_dispatch]\njobs:\n  verify:\n    runs-on: ubuntu-latest\n    strategy:\n      matrix:\n        node: [22, 24, 26]\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: \u0024{{ matrix.node }}\n      - uses: pnpm/action-setup@v4\n        with:\n          version: 10.15.0\n      - run: pnpm test\n      - run: pnpm verify-bundle\n      - run: npm pack\n      - run: |\n          mkdir -p /tmp/cli-consumer\n          npm install --prefix /tmp/cli-consumer --ignore-scripts ./\u0024(npm pkg get name | tr -d '\"')-\u0024(npm pkg get version | tr -d '\"').tgz\n          /tmp/cli-consumer/node_modules/.bin/${name} init --target-dir /tmp/harness-instance --project-name ci --json\n          /tmp/cli-consumer/node_modules/.bin/${name} sync --target-dir /tmp/harness-instance --json\n`,
+);
+write(root, ".gitignore", "node_modules/\n*.tgz\n.DS_Store\n");
+write(
+  root,
+  "yss-project.yaml",
+  "schema_version: 1\nrepository_mode: template-source\n",
+);
+write(
+  root,
+  "AGENTS.md",
+  "# CLI 维护入口\n\n本仓是模板工具链薄包，不生成产品 Spec / Ticket。公共实现权威位于综合模板 `.template-source/cli-core/`；`vendor/cli-core/` 和 `template/` 只通过同步脚本生成。修改身份时先更新来源 profile。日常 implementation-ready 可显式使用 `WORKTREE` 并在锁中记录来源状态；candidate/release 必须从完整提交重建。验证使用 `pnpm test`、`pnpm verify-bundle`，测试结束后才执行 `npm pack`。npm 发布和旧入口退役独立执行发布流程。\n",
+);
+write(
+  root,
+  "README.md",
+  `# ${name}\n\n创建、接入和同步 \`harness.${side}-delivery\` 的治理资产。CLI 包内包含固定模板与公共核心，init / attach / sync 离线运行。不会生成业务运行时代码。当前安装版本和 npm 发布状态分别以 \`${name} --version\` 与 registry 为准；本地候选可用 \`npm pack\` 后的实际 tgz 验收。\n\n\`\`\`sh\nnpx ${name}@latest init --target-dir ./my-project --project-name 我的项目\nnpx ${name}@latest attach --target-dir ./existing-project\nnpx ${name}@latest attach --target-dir ./existing-project --apply\nnpx ${name}@latest sync --target-dir ./my-project --plan --prune\nnpx ${name}@latest sync --target-dir ./my-project --apply --prune\nnpx ${name}@latest recover --target-dir ./my-project\n${name} update --dry-run\n\`\`\`\n\ninit 只接受不存在或空目录；\`--dry-run\` 不写入。attach / sync 默认预览，写入要求 \`--apply\`。治理冲突整次暂停，确认备份覆盖后可用 \`--apply --force\`。业务源码、构建文件、Git、子模块与越界路径不能强制接管。\n\n仓内旧脚本生成的实例不受支持，不转换旧 metadata 或重建基线；其他 Harness 家族同样拒绝。已有 metadata v2 实例使用同家族 sync。旧 \`docs/\` 治理文件迁移需显式 \`--migrate-layout\`，先用 \`--plan\` 审阅，再用 \`--apply\`；项目 tracker 保留原文，旧受管文件缺可信基线或已修改时阻断。普通 sync 保留退出分发文件；显式 \`--prune\` 只删除内容和 mode 仍等于可信旧 baseline 的文件，用户修改过的旧副本继续保留并报告。\n\n参数：\`--project-name\`、\`--business-domain\`、\`--team-size\`、\`--issue-tracker local-markdown|github|gitlab\`、\`--git-init\`（仅 init）、\`--include-example-docs\` / \`--no-example-docs\`、\`--json\`。程序升级命令 \`update\` / \`upgrade\` 只更新 CLI；npx、源码或未知安装方式输出安装指引。\n\n每次应用保存 \`.yss-harness-state/${side}/transactions/<id>/journal.json\` 和原文件备份。失败自动恢复；进程中断后先用 \`recover\` 诊断，带 \`--apply\` 才执行恢复。恢复遇到后续修改会停下并保留恢复清单。成功事务保留备份，但不提供历史 rollback。状态目录应由项目自行排除 Git；CLI 不改已有 Git 配置。\n\nJSON 协议版本 1：成功返回 \`preview\`、\`applied\`、\`recovered\`；错误退出码 1，含 \`code\` / \`message\`，冲突含完整 \`changes\` / \`conflicts\`。存在普通可应用更新的预览退出码为 0。\n\n维护：日常 implementation-ready 可运行 \`pnpm sync-core <source-repo> WORKTREE\` 和 \`pnpm sync-template <source-repo> WORKTREE\`，来源状态会写入锁和快照；candidate/release 必须改用完整 40 位提交。加 \`--check\` 只核验。\`pnpm test\` 完成后依次 \`pnpm verify-bundle\`、\`npm pack\` 和干净目录安装验收。来源锁和 blob 编码随包携带；不要手改生成文件。\n`,
+);
+write(
+  root,
+  "LICENSE",
+  "UNLICENSED\n\n本包遵循现有 YSS CLI 的分发许可标识。随包第三方资产保留各自的许可证与来源声明。\n",
+);
+console.log(root);