create-yss-spec 3.4.10 → 3.5.2

package/README.md

@@ -2,11 +2,11 @@
 
 用于初始化、接管已有项目并持续同步 `yss-spec-project-template` 研发管理资产的 npm CLI。
 
-源码候选版本：`3.4.9`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
+源码候选版本：`3.5.0`。当前固定模板身份、来源状态和摘要见 `template.snapshot.json`；CLI 运行时不会拉取模板仓库。`npm create yss-spec@latest` 获取的是实际已发布 npm 包，发布版本请以 `npm view create-yss-spec version` 为准，并用 `create-yss-spec --version` 核对当前执行版本。
 
 ## 本版模板能力
 
-本版同步 Handoff v5、领域与阶段决策、前后端交付边界和 committed-source 身份校验。CLI 仍会在同一事务内刷新生成型 `skills-lock.json`，再运行项目实例校验；刷新或校验失败恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
+本版新增按阶段分发项目实例资产及 `assets ensure` 命令；旧实例沿用原有分发范围。CLI 在同一事务内刷新生成型 `skills-lock.json` 并运行项目实例校验，失败时恢复同步前状态。版本升级只完成 GitHub 源码交付，npm 发布状态仍以 registry 为准。
 
 ## 快速开始
 
@@ -34,7 +34,7 @@ CLI 在规划和写入前检查模板家族身份，当前主路线识别：
 - `create-yss-harness-backend` / `.yss-harness-backend.json`
 - `create-yss-harness-frontend` / `.yss-harness-frontend.json`
 
-`docs/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
+`.template-spec/process/harness-profile.yaml` 也参与身份判断。异族、多重 identity、损坏 metadata、未知或矛盾 profile、identity symlink 均在写入前 fail closed，`--force` 不能绕过；Programmatic API 使用相同 guard。帮助和版本查询不受目标家族限制。
 
 旧 `create-yss-harness-dev` / `.yss-harness-dev.json` 仍会被识别并拒绝跨家族接管；既有实例按原固定版本维护，不再作为新项目入口。战略、后端和前端分别使用专职 CLI，任何家族都不做跨家族原地迁移。
 
@@ -183,4 +183,8 @@ npm pack --dry-run
 - [Ownership Policy v1](docs/implementation/ownership-policy-v1.md)
 - [Lifecycle Policies v1](docs/implementation/lifecycle-policies-v1.md)
 - [Programmatic API v1](docs/implementation/programmatic-api-v1.md)
-- [完整中文使用手册](docs/user-guide/create-yss-spec-cli-guide.md)
+- [完整中文使用手册](.template-spec/user-guide/create-yss-spec-cli-guide.md)
+
+## 治理目录迁移
+
+新实例将分发治理资产安装到 `.template-spec/`，项目规格产物放在 `docs/`。已有实例只有显式运行 `sync --migrate-layout --plan` 审阅后，才运行 `sync --migrate-layout --apply`；`attach` 同样支持该开关。迁移保留项目 tracker 配置，缺少可信摘要、旧文件被修改或目标路径冲突时阻断。普通 sync 不自动改变旧实例目录。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "3.4.10",
+  "version": "3.5.2",
   "description": "Initialize a YSS spec project template repository",
   "main": "src/api/index.js",
   "repository": {

package/src/api/_sync-service.js

@@ -2,19 +2,22 @@
 
 const fs = require("node:fs");
 const path = require("node:path");
+const { isDeepStrictEqual } = require("node:util");
 
 const { pathKind, targetPath, normalizeRelativePath } = require("../filesystem/path-utils");
 const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
 const { runInTransaction } = require("../filesystem/transaction-runner");
 const { assertBundledFamily, assertTargetFamily } = require("../family-runtime");
-const { gitDirtyWarning } = require("../git/worktree");
+const { collectGitRoots, gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildSyncPlanFromRuntime } = require("../template/sync-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { prepareLayoutMigration, combineMigrationPlans } = require("../template/layout-migration");
 const { classifyRemovedFiles } = require("../template/prune-planner");
 const { decorateMetadataOwnership } = require("../template/ownership-metadata");
 const { decorateMetadataLifecycle } = require("../template/lifecycle-metadata");
 const {
+  readProjectSkillLock,
   refreshGeneratedProjectInstance,
   verifyGeneratedProjectInstance,
 } = require("../template/verification-runtime");
@@ -47,7 +50,7 @@ function isInsideTemplateRoot(targetDir) {
   );
 }
 
-function inspectExistingTargetDir(targetDir, { force = false } = {}) {
+function inspectExistingTargetDir(targetDir, { force = false, gitRoots = null } = {}) {
   if (isInsideTemplateRoot(targetDir)) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
@@ -57,6 +60,7 @@ function inspectExistingTargetDir(targetDir, { force = false } = {}) {
   assertTargetWorkingTreeWritable(targetDir, {
     force,
     packageRoot: PACKAGE_ROOT,
+    ...(gitRoots && { deps: { collectGitRoots: () => gitRoots } }),
   });
 }
 
@@ -70,25 +74,35 @@ function affectedPathsForMigration(migrationPlan) {
   );
 }
 
-function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd() } = {}) {
+function buildSyncContext({ targetDir = ".", force = false, migrateLayout = false, cwd = process.cwd() } = {}) {
   const snapshot = readTemplateSnapshot();
   assertBundledFamily(snapshot);
   const resolvedTargetDir = normalizeTargetDir(targetDir, cwd);
   assertTargetFamily(resolvedTargetDir);
-  inspectExistingTargetDir(resolvedTargetDir, { force: Boolean(force) });
+  const gitRoots = collectGitRoots(resolvedTargetDir);
+  const securityOptions = { packageRoot: PACKAGE_ROOT, deps: { collectGitRoots: () => gitRoots } };
+  inspectExistingTargetDir(resolvedTargetDir, { force: Boolean(force), gitRoots });
 
   const { metadata } = loadTemplateMetadata(resolvedTargetDir);
   const identity = readTargetIdentity(resolvedTargetDir);
-  const desiredOperations = buildSyncDesiredOperations(
+  const baseDesiredOperations = buildSyncDesiredOperations(
     resolvedTargetDir,
     metadata,
     identity,
+    snapshot,
   );
-  const migrationPlan = buildLegacyMigrationPlan(
+  const layout = prepareLayoutMigration({
+    targetDir: resolvedTargetDir,
+    desiredOperations: baseDesiredOperations,
+    managedFiles: metadata.managedFiles || {},
+    explicit: migrateLayout,
+  });
+  const desiredOperations = layout.desiredOperations;
+  const migrationPlan = combineMigrationPlans(layout.plan, buildLegacyMigrationPlan(
     resolvedTargetDir,
     desiredOperations,
     { checkFlatTickets: false },
-  );
+  ));
   const warning = gitDirtyWarning(resolvedTargetDir);
 
   const { classified: syncPlan, plan } = buildSyncPlanFromRuntime({
@@ -99,19 +113,19 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
     warning,
     toVersion: PACKAGE_MANIFEST.version,
     getUnmanagedReason: (operation) =>
-      operation.unsafeReason || unmanagedPathReason(resolvedTargetDir, operation.relativePath, {
-        packageRoot: PACKAGE_ROOT,
-      }),
+      operation.unsafeReason || unmanagedPathReason(resolvedTargetDir, operation.relativePath, securityOptions),
     getPathKind: (operation) => pathKind(operation.targetPath),
     getFileHash: (operation) => fileHash(operation.targetPath),
   });
   const removedPlan = classifyRemovedFiles({
-    removed: syncPlan.removed.filter((relativePath) => relativePath !== "README.md"),
+    removed: syncPlan.removed.filter((relativePath) =>
+      relativePath !== "README.md" &&
+      !layout.plan.operations.some((operation) => operation.kind === "remove" && operation.path === relativePath)),
     managedFiles: metadata.managedFiles || {},
     getPathKind: (relativePath) => pathKind(targetPath(resolvedTargetDir, relativePath)),
     getFileHash: (relativePath) => fileHash(targetPath(resolvedTargetDir, relativePath)),
     getUnmanagedReason: (relativePath) =>
-      unmanagedPathReason(resolvedTargetDir, relativePath, { packageRoot: PACKAGE_ROOT }),
+      unmanagedPathReason(resolvedTargetDir, relativePath, securityOptions),
   });
   const readmeOwnershipTransferred = syncPlan.removed.includes("README.md");
   syncPlan.removed = syncPlan.removed.filter((relativePath) => relativePath !== "README.md");
@@ -133,10 +147,12 @@ function buildSyncContext({ targetDir = ".", force = false, cwd = process.cwd()
 
   return {
     targetDir: resolvedTargetDir,
+    snapshot,
     metadata,
     identity,
     desiredOperations,
     migrationPlan,
+    migrateLayout,
     warning,
     syncPlan,
     plan,
@@ -158,27 +174,118 @@ function assertSyncApplicable(context) {
   }
 }
 
+function isVerifiedNoopCandidate(context) {
+  const { metadata, migrationPlan, syncPlan } = context;
+  if (
+    syncPlan.updated.some((operation) => operation.relativePath !== "skills-lock.json") ||
+    syncPlan.added.length > 0 ||
+    syncPlan.skipped.length > 0 ||
+    syncPlan.removed.length > 0 ||
+    syncPlan.prunable.length > 0 ||
+    syncPlan.retainedRemoved.length > 0 ||
+    syncPlan.readmeOwnershipTransferred ||
+    (syncPlan.alreadyMissing || []).length > 0 ||
+    migrationPlan.operations.length > 0
+  ) return false;
+
+  const nextMetadata = decorateMetadataLifecycle(
+    decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan, {
+      snapshot: context.snapshot,
+      currentHashes: syncPlan.currentHashes,
+    })),
+  );
+  return isDeepStrictEqual(
+    { ...nextMetadata, lastSyncedAt: metadata.lastSyncedAt },
+    metadata,
+  );
+}
+
 function applySyncContext(context, { force = false, prune = false } = {}) {
   assertSyncApplicable(context);
-  const { targetDir, metadata, migrationPlan, syncPlan } = context;
+  const { targetDir, metadata, desiredOperations, migrationPlan, syncPlan } = context;
+  if (isVerifiedNoopCandidate(context)) {
+    try {
+      verifyGeneratedProjectInstance(targetDir);
+      return {
+        schemaVersion: APPLY_RESULT_SCHEMA_VERSION,
+        operation: "sync",
+        targetDir,
+        backupPath: null,
+        template: context.plan.template,
+        stats: { updated: 0, added: 0, skipped: 0, removed: 0, forceApplied: 0, pruned: 0 },
+        skipped: [],
+        removed: [],
+        prunable: [],
+        pruned: [],
+        retainedRemoved: [],
+        ownershipTransferred: [],
+      };
+    } catch {
+      // A stale generated lock needs the normal transactional refresh and verification.
+    }
+  }
+  const previousSkillLock = readProjectSkillLock(targetDir);
   const managedToApply = [
     ...syncPlan.updated,
     ...syncPlan.added,
     ...(force ? syncPlan.forceableConflicts : []),
   ];
   syncPlan.pruned = prune ? [...syncPlan.prunable] : [];
+  const affectedPaths = [
+    ...affectedPathsForManagedOperations(managedToApply),
+    ...affectedPathsForMigration(migrationPlan),
+    ...syncPlan.pruned,
+    "skills-lock.json",
+    TEMPLATE_METADATA_FILENAME,
+  ];
 
   const { backupPath } = runInTransaction({
     targetDir,
     operation: "sync",
-    affectedPaths: [
-      ...affectedPathsForManagedOperations(managedToApply),
-      ...affectedPathsForMigration(migrationPlan),
-      ...syncPlan.pruned,
-      "skills-lock.json",
-      TEMPLATE_METADATA_FILENAME,
-    ],
+    affectedPaths,
     execute: (transaction) => {
+      const gitRoots = collectGitRoots(targetDir);
+      const securityOptions = { packageRoot: PACKAGE_ROOT, deps: { collectGitRoots: () => gitRoots } };
+      assertTargetWorkingTreeWritable(targetDir, { ...securityOptions, force });
+      for (const relativePath of new Set(affectedPaths)) {
+        const reason = unmanagedPathReason(targetDir, relativePath, securityOptions);
+        if (reason) throw new Error(`${relativePath}: ${reason}`);
+        const kind = pathKind(targetPath(targetDir, relativePath));
+        if (kind === "other") throw new Error(`${relativePath}: 写入前路径类型已变化为 ${kind}`);
+        if (["skills-lock.json", TEMPLATE_METADATA_FILENAME].includes(relativePath) && kind === "directory") {
+          throw new Error(`${relativePath}: 写入前路径类型已变化为 ${kind}`);
+        }
+      }
+      if (!isDeepStrictEqual(loadTemplateMetadata(targetDir).metadata, metadata)) {
+        throw new Error("模板元数据在规划后已变化，请重新运行 sync");
+      }
+      for (const operation of managedToApply) {
+        const kind = pathKind(targetPath(targetDir, operation.relativePath));
+        const plannedHash = syncPlan.currentHashes[operation.relativePath];
+        if (plannedHash === undefined ? kind !== "missing" : kind !== "file" || fileHash(operation.targetPath) !== plannedHash) {
+          throw new Error(`${operation.relativePath}: 规划后目标文件已变化，请重新运行 sync`);
+        }
+      }
+      for (const relativePath of syncPlan.pruned) {
+        const current = targetPath(targetDir, relativePath);
+        if (pathKind(current) !== "file" || fileHash(current) !== metadata.managedFiles[relativePath]?.contentHash) {
+          throw new Error(`${relativePath}: 待清理文件在规划后已变化，请重新运行 sync`);
+        }
+      }
+      const currentLayout = prepareLayoutMigration({
+        targetDir,
+        desiredOperations: buildSyncDesiredOperations(targetDir, metadata, readTargetIdentity(targetDir), context.snapshot),
+        managedFiles: metadata.managedFiles || {},
+        explicit: context.migrateLayout,
+      });
+      const currentMigration = combineMigrationPlans(currentLayout.plan,
+        buildLegacyMigrationPlan(targetDir, desiredOperations, { checkFlatTickets: false }));
+      if (!isDeepStrictEqual(currentMigration.operations, migrationPlan.operations) ||
+          !isDeepStrictEqual(currentLayout.desiredOperations.map((operation) => [operation.relativePath, operation.desiredHash]),
+            desiredOperations.map((operation) => [operation.relativePath, operation.desiredHash])) ||
+          currentMigration.unsafe.length || currentMigration.conflicts.length) {
+        throw new Error("旧路径迁移在规划后已变化，请重新运行 sync");
+      }
       for (const operation of managedToApply) {
         applyManagedOperation(operation, transaction);
       }
@@ -187,12 +294,23 @@ function applySyncContext(context, { force = false, prune = false } = {}) {
         transaction.remove(targetPath(targetDir, relativePath));
       }
       verifyGeneratedSyncInstance(targetDir);
-      refreshGeneratedProjectInstance(targetDir);
+      refreshGeneratedProjectInstance(targetDir, {
+        previousSkillLock,
+        previousManagedFiles: metadata.managedFiles,
+        transaction,
+      });
       verifyGeneratedProjectInstance(targetDir);
       const nextMetadata = decorateMetadataLifecycle(
-        decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan)),
+        decorateMetadataOwnership(buildNextSyncMetadata(metadata, syncPlan, { snapshot: context.snapshot })),
       );
-      writeTemplateMetadata(targetDir, nextMetadata, transaction);
+      for (const operation of context.migrationPlan.operations) {
+        if (operation.kind === "remove" && operation.path.startsWith("docs/")) {
+          delete nextMetadata.managedFiles[operation.path];
+        }
+      }
+      if (!isDeepStrictEqual({ ...nextMetadata, lastSyncedAt: metadata.lastSyncedAt }, metadata)) {
+        writeTemplateMetadata(targetDir, nextMetadata, transaction);
+      }
     },
   });
 

package/src/cli/args.js

@@ -8,6 +8,7 @@ const VALUE_OPTIONS = new Map([
   ["--team-size", "teamSize"],
   ["--target-dir", "targetDir"],
   ["--issue-tracker", "issueTracker"],
+  ["--agent-runtime", "agentRuntime"],
 ]);
 
 function parseArgs(argv = []) {
@@ -38,6 +39,8 @@ function parseArgs(argv = []) {
       options.force = true;
     } else if (current === "--prune") {
       options.prune = true;
+    } else if (current === "--migrate-layout") {
+      options.migrateLayout = true;
     } else if (current === "--git-init") {
       options.gitInit = true;
     } else if (current === "--include-example-docs") {

package/src/cli/help.js

@@ -16,6 +16,8 @@ COMMANDS
   sync       同步已有模板实例的受管资产
   diff       只计算同步差异，不写入文件
   doctor     检查模板实例、身份、Git 和安全状态
+  skills     按需补装 Skill 或增加 Agent 平台
+  assets     按生命周期阶段补装所需文件与 Skill
   update     检查 npm 最新版本，如有更新则安装
   upgrade    update 的别名
 
@@ -25,6 +27,7 @@ OPTIONS
   --team-size <size>                 团队规模；init 不传则可留空，默认「待补充」
   --target-dir <dir>                 目标目录；init 不传则进入交互输入，sync/diff/doctor 默认为当前目录
   --issue-tracker github|gitlab      默认 issue tracker 偏好（默认 github）
+  --agent-runtime codex|cursor|pi    init/attach 必选；交互模式可在提示中选择
   --dry-run                          兼容预演模式，不写入文件
   --plan                             sync：输出结构化文本计划，不写入文件
   --json                             sync/diff/doctor：输出机器可读 JSON，不写入文件
@@ -33,8 +36,9 @@ OPTIONS
                                      attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
                                      update：即使已是最新时仍重新安装；npx / 源码目录仍不覆盖
   --prune                            sync：备份并删除与旧受管基线一致的退出分发文件
+  --migrate-layout                   attach/sync：显式迁移旧 docs 治理布局，冲突时停止并保留备份
   --git-init                         初始化完成后执行 git init
-  --include-example-docs             显式保留示例文档（默认开启）
+  --include-example-docs             显式保留示例文档（默认关闭）
   --no-example-docs                  不生成示例文档
   -h, --help                         显示本帮助信息
   -v, --version                      显示 CLI 版本
@@ -63,6 +67,8 @@ EXAMPLES
   $ npx create-yss-spec@latest sync
   $ npx create-yss-spec@latest sync --dry-run
   $ npx create-yss-spec@latest sync --plan
+  $ npx create-yss-spec@latest sync --plan --migrate-layout
+  $ npx create-yss-spec@latest sync --migrate-layout
   $ npx create-yss-spec@latest sync --json
   $ npx create-yss-spec@latest diff
   $ npx create-yss-spec@latest diff --json
@@ -70,6 +76,12 @@ EXAMPLES
   $ npx create-yss-spec@latest doctor --json
   $ npx create-yss-spec@latest sync --target-dir . --force
   $ npx create-yss-spec@latest sync --plan --prune
+  $ npx create-yss-spec@latest skills ensure yss-web-controller --plan
+  $ npx create-yss-spec@latest assets ensure stage.spec-architecture --plan
+  $ npx create-yss-spec@latest assets ensure stage.spec-architecture --apply
+  $ npx create-yss-spec@latest skills ensure yss-web-controller --apply
+  $ npx create-yss-spec@latest skills runtime add cursor --plan
+  $ npx create-yss-spec@latest skills runtime add cursor --apply
   $ npx create-yss-spec@latest sync --prune
   $ npx create-yss-spec update
   $ npx create-yss-spec update --dry-run
@@ -77,7 +89,7 @@ EXAMPLES
 
 LEARN MORE
   仓库 README：https://github.com/iloveZzz/create-yss-spec#readme
-  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/docs/user-guide/create-yss-spec-cli-guide.md
+  使用手册：https://github.com/iloveZzz/create-yss-spec/blob/main/.template-spec/user-guide/create-yss-spec-cli-guide.md
   模板仓库：https://github.com/iloveZzz/yss-spec-project-template
 `;
 }

package/src/cli/index.js

@@ -29,6 +29,7 @@ const { runDiff } = require("../commands/diff");
 const { runDoctor } = require("../commands/doctor");
 const { runInit } = require("../commands/init");
 const { runSync } = require("../commands/sync");
+const { runSkills, runAssets } = require("../commands/skills");
 const { runUpdateCommand } = require("../commands/update");
 const { printHelp, printVersion } = require("./help");
 const { resolveCommand } = require("./router");
@@ -58,6 +59,8 @@ async function runCli(argv = []) {
   if (route.command === "sync") {
     return runSync(route.args);
   }
+  if (route.command === "skills") return runSkills(route.args);
+  if (route.command === "assets") return runAssets(route.args);
   if (route.command === "doctor") {
     return runDoctor(route.args);
   }

package/src/cli/prompts.js

@@ -11,8 +11,9 @@ function normalizeInteractiveOptions(options, values) {
     gitInit: Boolean(options.gitInit),
     includeExampleDocs:
       options.includeExampleDocs === undefined
-        ? true
+        ? false
         : Boolean(options.includeExampleDocs),
+    ...(values.agentRuntime || options.agentRuntime ? { agentRuntime: values.agentRuntime || options.agentRuntime } : {}),
   };
 }
 
@@ -40,12 +41,14 @@ async function promptForMissingOptions(options, deps = {}) {
         : await rl.question("团队规模（可留空）: ");
     const targetDir =
       options.targetDir || (await rl.question("目标目录: ")).trim();
+    const agentRuntime = options.agentRuntime || (await rl.question("Agent 平台（codex/cursor/pi）: ")).trim();
 
     return normalizeInteractiveOptions(options, {
       projectName,
       businessDomain,
       teamSize: (teamSizeInput || "").trim() || "待补充",
       targetDir,
+      agentRuntime,
     });
   } finally {
     rl.close();
@@ -53,6 +56,7 @@ async function promptForMissingOptions(options, deps = {}) {
 }
 
 async function promptFromBufferedInput(options, deps = {}) {
+  if (!options.agentRuntime) throw new Error("无交互 init 必须显式指定 --agent-runtime codex|cursor|pi");
   const stdin = deps.stdin || process.stdin;
   const stdout = deps.stdout || process.stdout;
   const chunks = [];

package/src/cli/router.js

@@ -19,6 +19,8 @@ function resolveCommand(argv = []) {
   if (head === "sync") {
     return { command: "sync", args: rest };
   }
+  if (head === "skills") return { command: "skills", args: rest };
+  if (head === "assets") return { command: "assets", args: rest };
   if (head === "attach") {
     return { command: "attach", args: rest };
   }

package/src/commands/attach.js

@@ -4,6 +4,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const { parseArgs } = require("../cli/args");
+const { assertRuntime } = require("../template/distribution-runtime");
 const { pathKind, targetPath, normalizeRelativePath } = require("../filesystem/path-utils");
 const { applyManagedOperation, applyMigrationOperations } = require("../filesystem/apply-plan");
 const { runInTransaction } = require("../filesystem/transaction-runner");
@@ -12,6 +13,7 @@ const { gitDirtyWarning } = require("../git/worktree");
 const { unmanagedPathReason, assertTargetWorkingTreeWritable } = require("../validation/security");
 const { buildAttachPlanFromRuntime } = require("../template/attach-planner-runtime");
 const { buildLegacyMigrationPlan } = require("../template/migration-runtime");
+const { prepareLayoutMigration, combineMigrationPlans } = require("../template/layout-migration");
 const {
   PACKAGE_ROOT,
   BUNDLED_TEMPLATE_ROOT,
@@ -29,6 +31,8 @@ const {
 } = require("../template/verification-runtime");
 
 function assertRequiredOptions(options) {
+  if (!options.agentRuntime && !process.stdin.isTTY) throw new Error("无交互 attach 必须显式指定 --agent-runtime codex|cursor|pi");
+  if (options.agentRuntime) assertRuntime(options.agentRuntime);
   if (!options.projectName) {
     throw new Error("attach 需要 --project-name，项目名称不能为空");
   }
@@ -73,8 +77,9 @@ function attachVariables(options) {
     issueTracker: options.issueTracker || "github",
     includeExampleDocs:
       options.includeExampleDocs === undefined
-        ? true
+        ? false
         : Boolean(options.includeExampleDocs),
+    agentRuntime: options.agentRuntime,
   };
 }
 
@@ -156,8 +161,14 @@ function affectedPathsForMigration(migrationPlan) {
   );
 }
 
-function runAttach(argv = []) {
+async function runAttach(argv = []) {
   const options = parseArgs(argv);
+  if (!options.agentRuntime && process.stdin.isTTY) {
+    const readline = require("node:readline/promises");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try { options.agentRuntime = (await rl.question("Agent 平台（codex/cursor/pi）: ")).trim(); }
+    finally { rl.close(); }
+  }
   if (options.prune) throw new Error("--prune 仅适用于 sync");
   assertRequiredOptions(options);
 
@@ -180,14 +191,19 @@ function runAttach(argv = []) {
 
   const variables = attachVariables(options);
   const identity = readTargetIdentity(targetDir);
-  const desiredOperations = buildAttachDesiredOperations(
+  const baseDesiredOperations = buildAttachDesiredOperations(
     targetDir,
     variables,
     identity,
   );
-  const migrationPlan = buildLegacyMigrationPlan(targetDir, desiredOperations, {
-    checkFlatTickets: true,
+  const layout = prepareLayoutMigration({
+    targetDir, desiredOperations: baseDesiredOperations,
+    explicit: Boolean(options.migrateLayout),
   });
+  const desiredOperations = layout.desiredOperations;
+  const migrationPlan = combineMigrationPlans(layout.plan, buildLegacyMigrationPlan(targetDir, desiredOperations, {
+    checkFlatTickets: true,
+  }));
   const warning = gitDirtyWarning(targetDir);
 
   const { classified: plan } = buildAttachPlanFromRuntime({

package/src/commands/diff.js

@@ -8,6 +8,7 @@ const { projectDiff } = require("../api/project-diff");
 function runDiff(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   const plan = projectDiff({
     targetDir: options.targetDir || ".",
     force: Boolean(options.force),

package/src/commands/doctor.js

@@ -394,6 +394,7 @@ function renderDoctorText(report) {
 function runDoctor(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   const targetDir = normalizeTargetDir(options.targetDir);
   const report = buildDoctorReport(targetDir);
 

package/src/commands/init.js

@@ -4,6 +4,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const { parseArgs } = require("../cli/args");
+const { assertRuntime } = require("../template/distribution-runtime");
 const { promptForMissingOptions } = require("../cli/prompts");
 const { printHelp, printVersion } = require("../cli/help");
 const { pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
@@ -32,6 +33,7 @@ const {
 } = require("../template/verification-runtime");
 
 function assertRequiredOptions(options) {
+  assertRuntime(options.agentRuntime);
   if (!options.projectName) {
     throw new Error("init 需要 --project-name，项目名称不能为空");
   }
@@ -119,6 +121,7 @@ function parentDirectoryOperations(desiredOperations, targetDir) {
 async function runInit(argv = []) {
   const options = parseArgs(argv);
   if (options.prune) throw new Error("--prune 仅适用于 sync");
+  if (options.migrateLayout) throw new Error("--migrate-layout 仅适用于 attach/sync");
   if (options.help) {
     printHelp(PACKAGE_MANIFEST.version);
     return;
@@ -193,7 +196,7 @@ async function runInit(argv = []) {
       ? "2. 运行 git status 检查初始化结果"
       : "2. 如需版本管理，可执行 git init",
   );
-  console.log("3. 检查 AGENTS.md、README 和 docs 目录是否符合预期");
+  console.log("3. 检查 AGENTS.md、README 和 .template-spec 目录是否符合预期；docs 将在首次项目产出时创建");
 }
 
 module.exports = {