create-yss-spec 3.5.3 → 3.5.5

package/vendor/cli-core/command-runner.mjs

@@ -0,0 +1,107 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, rmSync, writeFileSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { fileURLToPath } from "node:url";
+
+function killTree(child, signal) {
+  if (!child.pid) return;
+  try {
+    if (process.platform === "win32") spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+    else process.kill(-child.pid, signal);
+  } catch (error) { if (error.code !== "ESRCH") throw error; }
+}
+
+/** Bounded lifetime for external tools; stdout is never mixed with progress. */
+export function runCommand(command, args, { cwd, env = process.env, timeoutMs = 0, signal, stdoutFile, stderrFile, secrets = [], progress = false } = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new TypeError("timeoutMs 必须是非负毫秒数");
+  if (signal?.aborted) return Promise.resolve({ status: 1, stdout: "", stderr: "command cancelled", termination: "cancelled", duration_ms: 0 });
+  return new Promise(resolve => {
+    const started = performance.now();
+    const argumentSecrets = args.flatMap(value => { try { const url = new URL(value); return url.password ? [url.password, decodeURIComponent(url.password)] : []; } catch { return []; } });
+    const secretNames = new Map(Object.entries(env).filter(([key]) => /(?:PASSWORD|TOKEN|SECRET)$/.test(key) || key === "MAVEN_REPO_USERNAME").map(([key,value]) => [value,key]));
+    const replacement = secret => secretNames.has(secret) ? `[REDACTED:${secretNames.get(secret)}]` : "[REDACTED]";
+    const sensitive = [...secrets, ...argumentSecrets, ...secretNames.keys()].filter(value => typeof value === "string" && value.length > 0).sort((a, b) => b.length - a.length);
+    const redact = text => sensitive.reduce((value, secret) => value.replaceAll(secret, replacement(secret)), text);
+    if (progress) process.stderr.write(`[开始] ${redact(command + " " + args.join(" "))}\n`);
+    for (const file of [stdoutFile, stderrFile]) if (file) writeFileSync(file, "");
+    const child = spawn(command, args, { cwd, env, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"] });
+    let termination = null, escalation, timer, errorMessage;
+    const makeStream = file => {
+      const decoder = new StringDecoder("utf8");
+      let pending = "", captured = "";
+      const emit = text => { captured += text; if (file) appendFileSync(file, text); };
+      function consume(final = false) {
+        let output = "", cursor = 0;
+        while (cursor < pending.length) {
+          const match = sensitive.find(secret => pending.startsWith(secret, cursor));
+          if (match) { output += replacement(match); cursor += match.length; continue; }
+          if (!final && sensitive.some(secret => secret.startsWith(pending.slice(cursor)))) break;
+          output += pending[cursor++];
+        }
+        pending = pending.slice(cursor);
+        emit(output);
+      }
+      return { write(bytes) { pending += decoder.write(bytes); consume(); }, end() { pending += decoder.end(); consume(true); return captured; } };
+    };
+    const stdout = makeStream(stdoutFile), stderr = makeStream(stderrFile);
+    function cancel(reason) {
+      if (termination) return;
+      termination = reason;
+      killTree(child, "SIGTERM");
+      escalation = setTimeout(() => killTree(child, "SIGKILL"), 1000);
+    }
+    const abort = () => cancel("cancelled");
+    const onInterrupt = () => cancel("cancelled");
+    signal?.addEventListener("abort", abort, { once: true });
+    process.on("SIGINT", onInterrupt); process.on("SIGTERM", onInterrupt);
+    if (timeoutMs) timer = setTimeout(() => cancel("timeout"), timeoutMs);
+    child.stdout.on("data", bytes => stdout.write(bytes));
+    child.stderr.on("data", bytes => stderr.write(bytes));
+    child.on("error", error => { errorMessage = redact(error.message); });
+    child.on("close", (code, exitSignal) => {
+      clearTimeout(timer); clearTimeout(escalation);
+      // A group leader can exit before its descendants close redirected streams.
+      if (termination) killTree(child, "SIGKILL");
+      signal?.removeEventListener("abort", abort);
+      process.off("SIGINT", onInterrupt); process.off("SIGTERM", onInterrupt);
+      const duration_ms = performance.now() - started;
+      const status = termination === "timeout" ? 124 : termination ? 1 : code ?? 1;
+      if (progress) process.stderr.write(`[${status === 0 ? "完成" : "失败"}] ${command} (${Math.round(duration_ms)}ms, exit=${status}${termination ? `, ${termination}` : ""})\n`);
+      resolve({ status, stdout: stdout.end(), stderr: stderr.end() + (errorMessage || ""), signal: exitSignal, termination, duration_ms });
+    });
+  });
+}
+
+// Synchronous API compatibility for existing generators/cache consumers. The worker
+// owns the process group and streams logs; it never updates project metadata.
+export function runCommandSync(command, args, options = {}) {
+  const result = spawnSync(process.execPath, [fileURLToPath(import.meta.url), "--worker"], {
+    input: JSON.stringify({ command, args, options }), encoding: "utf8", maxBuffer: 64 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "inherit"], env: options.env ?? process.env,
+  });
+  if (result.error || result.status !== 0) throw new TypeError(result.error?.message || "command worker failed");
+  return JSON.parse(result.stdout);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url) && process.argv[2] === "--worker") {
+  const parent = process.ppid;
+  let input = "";
+  for await (const bytes of process.stdin) input += bytes;
+  const { command, args, options } = JSON.parse(input);
+  const controller = new AbortController();
+  const watchParent = setInterval(() => {
+    if (process.ppid !== parent) controller.abort();
+    else {
+      try { process.kill(parent, 0); } catch (error) { if (error.code === "ESRCH") controller.abort(); }
+    }
+  }, 100);
+  try {
+    const result = await runCommand(command, args, { ...options, signal: controller.signal });
+    if (result.status !== 0) {
+      // Only caller-created temporary resources are supplied here. The worker
+      // also owns this cleanup when a terminated synchronous caller cannot run finally.
+      for (const directory of options.cleanupPathsOnFailure || []) rmSync(directory, { recursive: true, force: true });
+    }
+    if (process.ppid === parent) process.stdout.write(JSON.stringify(result));
+  } finally { clearInterval(watchParent); }
+}

package/vendor/cli-core/engine.mjs

@@ -0,0 +1,239 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { ensure, stat, safe, descriptor, same, hash, json } from "./io.mjs";
+import {
+  identity,
+  guardNestedRepository,
+  METADATA,
+  gitlinks,
+  recoveryIdentity,
+} from "./identity.mjs";
+import { preserved, userOwned } from "./family.mjs";
+import { mergeGitignore } from "./gitignore.mjs";
+import { prepareGenerated, verifyInstance } from "./verification.mjs";
+import { PROFILE, render } from "./bundle.mjs";
+import { inspectState, applyTransaction, recover } from "./transaction.mjs";
+import { prepareLayoutMigration } from "./layout-migration.mjs";
+export function execute(bundle, target, opts) {
+  const { family: f, pkg, snapshot, core } = bundle;
+  const state = inspectState(target, f);
+  if (state.pending.length) {
+    for (const ref of METADATA.filter((x) => x !== f.metadataFile))
+      ensure(
+        !stat(safe(target, ref)),
+        "异族 metadata 禁止事务恢复",
+        "IDENTITY",
+      );
+    ensure(
+      opts.apply && !opts.dryRun && !opts.plan && opts.command !== "diff",
+      "发现中断事务；使用 --apply 恢复后重试",
+      "INTERRUPTED",
+    );
+    recoveryIdentity(target, bundle, state);
+    return recover(target, f, state, () =>
+      recoveryIdentity(target, bundle, state),
+    );
+  }
+  if (opts.command === "init")
+    ensure(
+      !stat(target) || fs.readdirSync(target).length === 0,
+      "init 只允许不存在或空目录；已有项目请使用 attach",
+    );
+  else ensure(stat(target)?.isDirectory(), "attach/sync 目标目录不存在");
+  const meta = identity(target, bundle, opts.command, opts.migrateLayout);
+  const canForce = f.side !== "design" && opts.force && opts.apply;
+  const variables = meta?.variables || {
+    projectName: opts.projectName || path.basename(target),
+    businessDomain: opts.businessDomain,
+    teamSize: opts.teamSize,
+    issueTracker: opts.issueTracker,
+    includeExampleDocs: opts.includeExampleDocs,
+  };
+  const protectedLinks = gitlinks(target);
+  const files = render(bundle, variables);
+  const layout = prepareLayoutMigration(target, meta, files, opts);
+  for (const [ref, bytes] of layout.replacements) {
+    files.set(ref, {bytes, baseline:{type:'file',digest:hash(bytes),mode:0o644}});
+  }
+  const legacyRefs = new Set(layout.legacyFiles);
+  const
+    managedFiles = {},
+    operations = [],
+    changes = [],
+    conflicts = [],
+    observed = new Map();
+  for (const ref of [
+    ...new Set([...files.keys(), ...Object.keys(meta?.managedFiles || {}), ...Object.keys(bundle.retiredFiles || {})]),
+  ].sort()) {
+    if (legacyRefs.has(ref)) continue;
+    ensure(
+      !protectedLinks.some((x) => ref === x || ref.startsWith(x + "/")),
+      `受保护 gitlink: ${ref}`,
+      "PROTECTED",
+    );
+    guardNestedRepository(target, ref);
+    const before = descriptor(target, ref);
+    let next = files.get(ref);
+    if (ref === '.gitignore' && next) {
+      const bytes = mergeGitignore(before ? fs.readFileSync(safe(target, ref)) : null, next.bytes, f);
+      next = {bytes, baseline:{type:'file',digest:hash(bytes),mode:before?.mode || 0o644}};
+    }
+    const after = next?.baseline || null, record = meta?.managedFiles[ref], retiredBaseline = bundle.retiredFiles?.[ref], transitionBaseline = meta ? bundle.transitionBaselines?.[ref] : null, baseline = record?.baseline || (transitionBaseline ? {type:'file',digest:transitionBaseline.digest,mode:transitionBaseline.mode} : null) || (retiredBaseline ? {type:'file',digest:retiredBaseline.digest,mode:retiredBaseline.mode} : null);
+    let action, reason;
+    observed.set(ref, before);
+    if (userOwned(ref, f)) {
+      action = before ? 'preserve' : (next && opts.command !== 'sync' && opts.command !== 'diff' ? 'add' : 'preserve');
+      reason = 'user-owned';
+    } else if (preserved(ref) && before) { action='preserve';reason='project-owned-content'; }
+    else if (!next) {
+      const retiredRecord = record || (retiredBaseline ? {baseline,lastApplied:null,ownership:'managed',retired:true} : null);
+      const eligible = retiredRecord && !retiredRecord.legacyUnproven && ref !== '.gitignore' && same(before, baseline) && before;
+      action = eligible && opts.prune ? 'delete' : 'preserve';
+      reason = eligible ? (opts.prune ? 'prune' : 'prunable') : 'retained-removed';
+      if (before && action !== 'delete' && retiredRecord) managedFiles[ref] = {...retiredRecord,retired:true};
+    } else if (same(before, after)) action='unchanged';
+    else if (ref === '.gitignore' || ref === 'skills-lock.json') action=before?'update':'add';
+    else if (!before || same(before, baseline) || (record?.legacyUnproven && before?.digest === baseline?.digest)) action=before?'update':'add';
+    else if (!record?.legacyUnproven && same(after, baseline)) action='preserve';
+    else action='conflict';
+    const resolution = opts.migrationResolutions?.[ref];
+    let merged;
+    if (resolution) {
+      ensure(action === 'conflict' && baseline && !record?.legacyUnproven, `不能合并非可信冲突: ${ref}`, 'CONFLICT');
+      ensure(resolution.beforeDigest === before?.digest && resolution.templateDigest === after?.digest, `冲突决议已过期: ${ref}`, 'CONCURRENT');
+      ensure(['preserve','merge'].includes(resolution.action), `未知冲突决议: ${ref}`);
+      if (resolution.action === 'preserve') action = 'preserve';
+      else {
+        ensure(typeof resolution.contentBase64 === 'string', `缺少合并内容: ${ref}`);
+        merged = Buffer.from(resolution.contentBase64, 'base64');
+        action = 'update';
+      }
+    }
+    if (action === 'conflict') conflicts.push(ref);
+    if (next && !userOwned(ref,f)) managedFiles[ref] = {
+      baseline:after,lastApplied:action==='preserve'?before:merged?{type:'file',digest:hash(merged),mode:before.mode}:after,ownership:ref==='skills-lock.json'?'generated':'managed',
+      ...(record?.legacyUnproven && action==='preserve' ? {legacyUnproven:true} : {}),
+    };
+    if (['update','add','delete'].includes(action) || (action==='conflict' && canForce)) operations.push({path:ref,before,after:merged?{type:'file',digest:hash(merged),mode:before.mode}:after,bytes:merged || next?.bytes});
+    changes.push({path:ref,action,...(reason?{reason}:{})});
+  }
+  for (const ref of Object.keys(opts.migrationResolutions || {})) ensure(changes.some(c=>c.path===ref) && !conflicts.includes(ref), `未消费的冲突决议: ${ref}`, 'CONFLICT');
+  for (const operation of layout.deletions) {
+    guardNestedRepository(target, operation.path);
+    ensure(!protectedLinks.some((x) => operation.path === x || operation.path.startsWith(x + "/")), `受保护 gitlink: ${operation.path}`, "PROTECTED");
+    observed.set(operation.path, operation.before);
+    operations.push(operation);
+    changes.push({path:operation.path,action:'delete',reason:'migrate-layout'});
+  }
+  const result = {
+    schemaVersion: 1,
+    command: opts.command,
+    status: "preview",
+    target,
+    cliVersion: pkg.version,
+    templateCommit: snapshot.templateCommit,
+    templateSourceState: snapshot.sourceState || "committed",
+    coreSourceState: core.sourceState || "committed",
+    coreVersion: core.coreVersion,
+    changes,
+    conflicts,
+    conflictDetails: conflicts.map(ref=>({path:ref,beforeDigest:observed.get(ref)?.digest,templateDigest:files.get(ref)?.baseline?.digest,resolutionSupported:Boolean(meta?.managedFiles?.[ref]?.baseline && !meta.managedFiles[ref].legacyUnproven)})),
+    backupPath: null,
+  };
+  if (conflicts.length && !canForce)
+    throw Object.assign(
+      new Error(
+        `治理文件冲突，整次暂停；确认备份覆盖后使用 --apply --force: ${conflicts.join(", ")}`,
+      ),
+      { code: "CONFLICT", result },
+    );
+  result.summary = Object.fromEntries(['add','update','delete','preserve','conflict','unchanged'].map(action=>[action,changes.filter(c=>c.action===action).length]));
+  result.prunable = changes.filter(c=>['prunable','prune'].includes(c.reason)).map(c=>c.path);
+  result.retainedRemoved = changes.filter(c=>c.reason==='retained-removed').map(c=>c.path);
+  result.pruned = [];
+  result.migrationRequired = Boolean(meta?.legacy || layout.legacyFiles.length);
+  result.legacyRetainedFiles = meta?.legacyRetainedFiles || [];
+  if (opts.dryRun || opts.plan || opts.command === 'diff' || (opts.command !== "init" && !opts.apply)) return result;
+  const watched = [...METADATA, "yss-project.yaml", PROFILE, ".gitmodules"];
+  const beforeIdentity = new Map(
+    watched.map((ref) => [ref, descriptor(target, ref)]),
+  );
+  const transactionId = opts.migrationId || randomUUID();
+  const metadata = {
+    lastTransactionId: transactionId,
+    metadataSchemaVersion: 2,
+    profileId: f.profileId,
+    templateName: f.templateName,
+    templateSource: f.templateSource,
+    cliVersion: pkg.version,
+    templateCommit: snapshot.templateCommit,
+    templateSourceState: snapshot.sourceState || "committed",
+    coreSourceState: core.sourceState || "committed",
+    snapshotHash: snapshot.snapshotHash,
+    coreVersion: core.coreVersion,
+    coreDigest: core.digest,
+    manifestHash: snapshot.manifestHash,
+    variables,
+    managedFiles,
+    ...(meta?.legacyRetainedFiles?.length ? {legacyRetainedFiles:meta.legacyRetainedFiles} : {}),
+    baselineDigest: hash(JSON.stringify(managedFiles)),
+    initializedAt: meta?.initializedAt || new Date().toISOString(),
+    lastSyncedAt: opts.migrationTime || new Date().toISOString(),
+  };
+  prepareGenerated(bundle, target, operations, metadata, observed);
+  if (!operations.length && meta && !meta.legacy && meta.snapshotHash === snapshot.snapshotHash && meta.coreDigest === core.digest && meta.cliVersion === pkg.version) return opts.captureMigration ? opts.captureMigration([], result) : {...result,status:'applied',message:'受管资产已是当前版本，无需写入'};
+  metadata.baselineDigest = hash(JSON.stringify(metadata.managedFiles));
+  const bytes = Buffer.from(json(metadata));
+  operations.push({
+    path: f.metadataFile,
+    before: descriptor(target, f.metadataFile),
+    after: { type: "file", digest: hash(bytes), mode: 0o644 },
+    bytes,
+  });
+  if (opts.captureMigration) return opts.captureMigration(operations, result);
+  // Metadata is last. Identity files already applied by this transaction have their new expected digest.
+  const opMap = new Map(operations.map((x) => [x.path, x]));
+  const validate = (operation) => {
+    if (!operation) {
+      ensure(
+        JSON.stringify(gitlinks(target)) === JSON.stringify(protectedLinks),
+        "gitlink 在计划后变化",
+        "CONCURRENT",
+      );
+      for (const [ref, before] of observed) {
+        const op = opMap.get(ref);
+        if (!op)
+          ensure(
+            same(descriptor(target, ref), before),
+            `未写入的受管文件并发变化: ${ref}`,
+            "CONCURRENT",
+          );
+      }
+    }
+    for (const [ref, before] of beforeIdentity) {
+      const op = opMap.get(ref),
+        current = descriptor(target, ref);
+      ensure(
+        same(current, before) || (op && same(current, op.after)),
+        `身份文件并发变化: ${ref}`,
+        "CONCURRENT",
+      );
+    }
+    if (operation) guardNestedRepository(target, operation.path);
+  };
+  return {
+    ...result,
+    status: "applied",
+    ...applyTransaction(
+      target,
+      f,
+      operations,
+      validate,
+      transactionId,
+      opts.gitInit,
+      () => verifyInstance(bundle, target),
+    ),
+    pruned: changes.filter(c=>c.action==='delete').map(c=>c.path),
+  };
+}

package/vendor/cli-core/family.mjs

@@ -0,0 +1,28 @@
+import { ensure } from './io.mjs';
+export const FAMILIES = Object.freeze(Object.fromEntries(['design', 'backend', 'frontend'].map(side => [side, Object.freeze({
+  side,
+  packageName: `create-yss-harness-${side}`,
+  profileId: side === 'design' ? 'harness.business-ddd-strategy-handoff' : `harness.${side}-delivery`,
+  metadataFile: `.yss-harness-${side}.json`,
+  templateName: `yss-harness-${side}-agent`,
+  templateSource: `github:iloveZzz/yss-harness-${side}-agent`,
+})])));
+export function familyFor(side) {
+  ensure(Object.hasOwn(FAMILIES, side), '未知 CLI 家族', 'IDENTITY');
+  return FAMILIES[side];
+}
+export function preserved(ref) { return ['README.md', 'CONTEXT.md', 'DESIGN.md', '.template-spec/agents/issue-tracker.md'].includes(ref); }
+export function userOwned(ref, family) {
+  if (['README.md', 'DESIGN.md'].includes(ref)) return true;
+  if (ref === 'CONTEXT.md') return false;
+  // Only reusable governance assets are eligible for recurring ownership.
+  if (family.side === 'design') return !(/^(?:\.(?:agents|claude|codex|cursor|pi|qoder|trae)\/skills\/|scripts\/|\.template-spec\/(?:agents\/|process\/|templates\/|user-guide\/|architecture\/templates\/))/.test(ref)
+    || ['.gitignore', '.nvmrc', 'AGENTS.md', 'CLAUDE.md', '.cursorrules', 'skills-lock.json', 'yss-project.yaml'].includes(ref));
+  return /^(?:docs\/(?:\.scratch|reviews|releases|requirements|implementation|api|adr)(?:\/|$))/.test(ref);
+}
+export const CHECKS = [
+  ['layout', 'scripts/verify-governance-layout'],
+  ['context', 'scripts/verify-context-contract', '--root', '.', '--json'],
+  ['profile', 'scripts/verify-harness-profile'],
+  ['skill-lock', 'scripts/update-skill-lock', '--check'],
+];

package/vendor/cli-core/gitignore.mjs

@@ -0,0 +1,15 @@
+import { ensure } from './io.mjs';
+export function mergeGitignore(current, template, family) {
+  const start = `# >>> ${family.packageName} managed rules`;
+  const end = `# <<< ${family.packageName} managed rules`;
+  const body = Buffer.from(`${start}\n${template.toString().replace(/\s*$/, '')}\n.yss-harness-state/\n${end}\n`);
+  const before = current || Buffer.alloc(0);
+  const a = before.indexOf(start), b = before.indexOf(end);
+  ensure((a === -1 && b === -1) || (a >= 0 && b > a && before.indexOf(start, a + 1) === -1 && before.indexOf(end, b + 1) === -1), '.gitignore 受管标记损坏或重复', 'GITIGNORE');
+  if (a === -1) return Buffer.concat([before, before.length && before.at(-1) !== 10 ? Buffer.from('\n') : Buffer.alloc(0), body]);
+  ensure((a === 0 || before[a - 1] === 10) && [undefined, 10, 13].includes(before[b + Buffer.byteLength(end)]), '.gitignore 标记必须独占一行', 'GITIGNORE');
+  let tail = b + Buffer.byteLength(end);
+  if (before[tail] === 13) tail++;
+  if (before[tail] === 10) tail++;
+  return Buffer.concat([before.subarray(0, a), body, before.subarray(tail)]);
+}

package/vendor/cli-core/identity.mjs

@@ -0,0 +1,274 @@
+import * as fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  ensure,
+  safe,
+  stat,
+  readJson,
+  governance,
+  hash,
+  relative,
+  descriptor,
+  same,
+} from "./io.mjs";
+import { yaml, PROFILE } from "./bundle.mjs";
+import { normalizeLegacy } from './legacy.mjs';
+export const METADATA = [
+  ".yss-template.json",
+  ".yss-harness-design.json",
+  ".yss-harness-dev.json",
+  ".yss-harness-backend.json",
+  ".yss-harness-frontend.json",
+];
+function validDescriptor(d, nullable = false) {
+  return (
+    (nullable && d === null) ||
+    Boolean(
+      d &&
+        d.type === "file" &&
+        /^[a-f0-9]{64}$/.test(d.digest) &&
+        Number.isInteger(d.mode) &&
+        d.mode >= 0 &&
+        d.mode <= 0o777,
+    )
+  );
+}
+export function identity(target, bundle, command, migrateLayout = false) {
+  const f = bundle.family,
+    present = METADATA.filter((ref) => stat(safe(target, ref)));
+  ensure(present.length <= 1, "检测到多个家族 metadata，拒绝混用", "IDENTITY");
+  ensure(
+    !present.length || present[0] === f.metadataFile,
+    "不同 Harness 家族不可接管或转换",
+    "IDENTITY",
+  );
+  let meta = null;
+  if (present.length) {
+    meta = readJson(target, f.metadataFile);
+    yaml(fs.readFileSync(safe(target, f.metadataFile)));
+    ensure(
+      meta && typeof meta === "object" && !Array.isArray(meta),
+      "metadata 必须是对象",
+      "IDENTITY",
+    );
+    ensure(
+      !("schema_version" in meta) &&
+        !("profile_id" in meta) &&
+        !("managed_files" in meta) &&
+        !("template_source" in meta),
+      "不支持旧实例；请在全新目录使用新 CLI init",
+      "LEGACY",
+    );
+    const legacy = f.side === "design" && meta.metadataSchemaVersion === 1;
+    if (legacy) meta = normalizeLegacy(meta, f);
+    if (!legacy) {
+    ensure(!meta.legacy, "非法 legacy 标记", "BASELINE");
+    ensure(
+      meta.metadataSchemaVersion === 2,
+      "不支持或损坏的 metadata schema",
+      "IDENTITY",
+    );
+    for (const key of ["profileId", "templateName", "templateSource"])
+      ensure(meta[key] === f[key], `metadata 身份矛盾: ${key}`, "IDENTITY");
+    ensure(
+      /^[a-f0-9]{40}$/.test(meta.templateCommit) &&
+        ["committed", "working-tree"].includes(meta.templateSourceState || "committed") &&
+        ["committed", "working-tree"].includes(meta.coreSourceState || "committed") &&
+        ["snapshotHash", "coreDigest", "manifestHash", "baselineDigest"].every(
+          (k) => /^[a-f0-9]{64}$/.test(meta[k]),
+        ),
+      "metadata 来源或摘要缺失",
+      "BASELINE",
+    );
+    ensure(
+      meta.managedFiles &&
+        typeof meta.managedFiles === "object" &&
+        !Array.isArray(meta.managedFiles) &&
+        hash(JSON.stringify(meta.managedFiles)) === meta.baselineDigest,
+      "基线缺失或摘要损坏；请使用保留的恢复清单",
+      "BASELINE",
+    );
+    for (const [ref, item] of Object.entries(meta.managedFiles)) {
+      governance(ref);
+      ensure(
+        validDescriptor(item.baseline) &&
+          validDescriptor(item.lastApplied, true),
+        `未知基线或文件类型: ${ref}`,
+        "BASELINE",
+      );
+    }
+    for (const ref of ["yss-project.yaml", "AGENTS.md", "CONTEXT.md"])
+      ensure(meta.managedFiles[ref], `基线缺少必需合同: ${ref}`, "BASELINE");
+    ensure(meta.managedFiles[PROFILE] || (migrateLayout && meta.managedFiles["docs/process/harness-profile.yaml"]), `基线缺少必需合同: ${PROFILE}`, "BASELINE");
+    ensure(
+      meta.variables &&
+        typeof meta.variables.projectName === "string" &&
+        typeof meta.variables.includeExampleDocs === "boolean",
+      "项目变量缺失",
+      "BASELINE",
+    );
+  }
+  }
+  const profilePath = safe(target, stat(safe(target, PROFILE)) ? PROFILE : (migrateLayout ? "docs/process/harness-profile.yaml" : PROFILE));
+  let profile = null;
+  if (stat(profilePath)) {
+    profile = yaml(fs.readFileSync(profilePath));
+    ensure(
+      profile.instantiation?.cli_package !== "repository-local",
+      "不支持 repository-local 旧实例；仅允许全新目录 init",
+      "LEGACY",
+    );
+    ensure(
+      [1, 2].includes(profile.schema_version) &&
+        profile.profile_id === f.profileId,
+      "目标 profile 未知或属于不同家族",
+      "IDENTITY",
+    );
+    ensure(
+      (f.side === "design" && !profile.instantiation) || (profile.instantiation?.cli_package === f.packageName &&
+        profile.instantiation?.metadata_file === f.metadataFile &&
+        profile.instantiation?.template_source === f.templateSource),
+      "目标 profile 字段矛盾",
+      "IDENTITY",
+    );
+    ensure(
+      meta,
+      "profile 存在但新版 metadata 缺失，无法建立所有权",
+      "BASELINE",
+    );
+  }
+  const projectPath = safe(target, "yss-project.yaml");
+  let project = null;
+  if (stat(projectPath)) {
+    project = yaml(fs.readFileSync(projectPath));
+    ensure(
+      project.schema_version === 1 &&
+        project.repository_mode === "project-instance",
+      "仓库 schema 不支持或不是 project-instance",
+      "IDENTITY",
+    );
+    ensure(meta, "已有 Harness 身份但缺少新版 metadata", "BASELINE");
+  }
+  if (meta)
+    ensure(profile && project, "metadata 存在但身份合同缺失", "IDENTITY");
+  if (["sync", "diff", "doctor", "recover"].includes(command))
+    ensure(meta, "sync 仅支持新 CLI 创建或 attach 的实例", "BASELINE");
+  else ensure(!meta, "已接入该家族，请使用 sync", "IDENTITY");
+  return meta;
+}
+export function guardNestedRepository(target, ref) {
+  let current = path.dirname(ref);
+  while (current !== ".") {
+    ensure(
+      !stat(safe(target, `${current}/.git`)),
+      `受保护嵌套仓库或 gitlink: ${current}`,
+      "PROTECTED",
+    );
+    current = path.dirname(current);
+  }
+}
+export function gitlinks(target) {
+  const paths = [];
+  const config = safe(target, ".gitmodules");
+  if (stat(config)) {
+    const r = spawnSync(
+      "git",
+      [
+        "config",
+        "--no-includes",
+        "--file",
+        config,
+        "--get-regexp",
+        "^submodule\\..*\\.path$",
+      ],
+      { encoding: "utf8" },
+    );
+    ensure(
+      [0, 1].includes(r.status),
+      `无法解析 .gitmodules: ${r.stderr}`,
+      "PROTECTED",
+    );
+    for (const line of r.stdout.trim().split("\n").filter(Boolean)) {
+      const value = line.replace(/^\S+\s+/, "");
+      relative(value);
+      paths.push(value);
+    }
+  }
+  if (stat(path.join(target, ".git"))) {
+    const r = spawnSync(
+      "git",
+      [
+        "--no-optional-locks",
+        "-c",
+        "core.fsmonitor=false",
+        "-C",
+        target,
+        "ls-files",
+        "--stage",
+        "-z",
+      ],
+      { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+    );
+    ensure(r.status === 0, `无法核验 Git index: ${r.stderr}`, "PROTECTED");
+    for (const record of r.stdout.split("\0"))
+      if (record.startsWith("160000 ")) {
+        const ref = record.slice(record.indexOf("\t") + 1);
+        relative(ref);
+        paths.push(ref);
+      }
+  }
+  return [...new Set(paths)].sort();
+}
+// A partially applied init/attach may not have metadata yet. Every identity byte
+// that does exist must still belong to this family and to the recorded transaction.
+export function recoveryIdentity(target, bundle, state) {
+  const f = bundle.family;
+  for (const ref of METADATA)
+    if (ref !== f.metadataFile)
+      ensure(
+        !stat(safe(target, ref)),
+        "异族 metadata 禁止事务恢复",
+        "IDENTITY",
+      );
+  if (stat(safe(target, f.metadataFile))) identity(target, bundle, "sync");
+  else {
+    if (stat(safe(target, PROFILE))) {
+      const p = yaml(fs.readFileSync(safe(target, PROFILE)));
+      ensure(
+        p.instantiation?.cli_package !== "repository-local",
+        "旧实例不支持恢复或接管",
+        "LEGACY",
+      );
+      ensure(
+        [1, 2].includes(p.schema_version) &&
+          p.profile_id === f.profileId &&
+          ((f.side === "design" && !p.instantiation) || (p.instantiation?.cli_package === f.packageName &&
+          p.instantiation?.metadata_file === f.metadataFile &&
+          p.instantiation?.template_source === f.templateSource)),
+        "恢复 profile 身份矛盾",
+        "IDENTITY",
+      );
+    }
+    if (stat(safe(target, "yss-project.yaml"))) {
+      const p = yaml(fs.readFileSync(safe(target, "yss-project.yaml")));
+      ensure(
+        p.schema_version === 1 && p.repository_mode === "project-instance",
+        "恢复仓库身份非法",
+        "IDENTITY",
+      );
+    }
+  }
+  for (const ref of [f.metadataFile, PROFILE, "yss-project.yaml"]) {
+    const current = descriptor(target, ref),
+      ops = state.pending
+        .flatMap((x) => x.journal.operations)
+        .filter((x) => x.path === ref);
+    if (ops.length)
+      ensure(
+        ops.some((op) => same(current, op.before) || same(current, op.after)),
+        `恢复身份已发生后续修改: ${ref}`,
+        "IDENTITY",
+      );
+  }
+}