create-yss-spec 2.1.14 → 2.2.0

package/README.md

@@ -14,6 +14,18 @@ npm create yss-spec@latest
 npx create-yss-spec@latest
 ```
 
+查看用法、命令、参数和样例：
+
+```bash
+npx create-yss-spec@latest --help
+```
+
+查看 CLI 版本：
+
+```bash
+npx create-yss-spec@latest --version
+```
+
 ## 当前支持
 
 - 交互式收集 `projectName`、`businessDomain`、`targetDir`
@@ -32,8 +44,10 @@ npx create-yss-spec@latest
 - 接管 / 升级时迁移 Spec / Ticket 路径并删除 `to-prd`、`to-issues` 旧 skill
 - 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
 - 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
+- init / sync 不把模板源治理笔记、wiki、审查证据、源仓 CI / Cloud 环境和公开发布清单写入项目实例；attach 会带上 `yss-public-skills.json` 供 `verify-template` 使用
+- 空 gitlink / detached HEAD / git-submodule 挂载点 fail closed，`--force` 也不能覆盖
 
-本次模板适配按 `2.1.14` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.2.0` 发布，绑定 `yss-spec-project-template@04a6151`。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 
@@ -60,6 +74,7 @@ npx create-yss-spec@latest attach \
 - 根规则文件等受管冲突默认阻断；`--force` 才覆盖，并把被覆盖文件备份到目标目录外的临时目录。
 - 合法 `template-source` 身份会转换为 `project-instance`；非法身份、迁移冲突和无法判断归属的扁平 Ticket 始终阻断。
 - Git worktree 有脏改动时只提醒，不自动 stash 或提交。
+- `.gitmodules`、gitlink 和 `apps/` 挂载工作树是用户资产；空 gitlink / detached HEAD 即使 `--force` 也阻断。
 
 ## 同步已有模板实例仓库
 
@@ -84,7 +99,8 @@ npx create-yss-spec@latest sync --dry-run
 - 对模板已删除文件只报告，不自动删除
 - 对已知的 Spec / Ticket 旧路径执行一次性迁移
 - 迁移目标已存在且内容不一致时停止，不静默覆盖
-- 同步结束会重新执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`；门禁失败会回滚文件和 metadata
+- `.gitmodules`、gitlink（mode `160000`）和 `apps/` 下已挂载实现仓是用户资产，不创建、不覆盖、不删除
+- init / sync 保持瘦实例：不复制 `scripts/`、`wiki/`、`.github/`、`.nvmrc`、`.gitignore`、`.template-source/`；attach 结束后会执行 `scripts/sync-skills --check`、`scripts/update-skill-lock --check` 和 `scripts/verify-template`，门禁失败会回滚文件和 metadata
 
 ```bash
 npx create-yss-spec@latest sync --target-dir . --dry-run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-yss-spec",
-  "version": "2.1.14",
+  "version": "2.2.0",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -33,15 +33,27 @@ const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
 const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
 const TEMPLATE_SOURCE = "github:iloveZzz/yss-spec-project-template";
 const METADATA_SCHEMA_VERSION = 2;
+const HELP_FLAGS = new Set(["--help", "-h", "-help"]);
+const VERSION_FLAGS = new Set(["--version", "-v", "-version"]);
 const AGENT_SKILL_ROOTS = [
   ".agents/skills",
   ".claude/skills",
   ".codex/skills",
+  ".cursor/skills",
   ".hermes/skills",
   ".pi/skills",
   ".qoder/skills",
   ".trae/skills",
 ];
+const GITLINK_MODE = "160000";
+const UNMANAGED_USER_PATHS = new Set([".gitmodules"]);
+const INSTANCE_FORBIDDEN_PATHS = [
+  ".template-source",
+  ".github",
+  ".cursor/environment.json",
+  "wiki",
+  "docs/reviews",
+];
 const LEGACY_SKILL_MAPPINGS = [
   ["to-prd", "to-spec"],
   ["to-issues", "to-tickets"],
@@ -184,8 +196,10 @@ function parseArgs(argv) {
       options.includeExampleDocs = true;
     } else if (current === "--no-example-docs") {
       options.includeExampleDocs = false;
-    } else if (current === "--help" || current === "-h") {
+    } else if (HELP_FLAGS.has(current)) {
       options.help = true;
+    } else if (VERSION_FLAGS.has(current)) {
+      options.version = true;
     } else {
       throw new Error(`不支持的参数：${current}`);
     }
@@ -297,6 +311,235 @@ function isInsideTemplateRoot(targetDir) {
   );
 }
 
+function posixRelative(from, to) {
+  return path.relative(from, to).split(path.sep).join("/");
+}
+
+function collectGitRoots(start) {
+  const roots = [];
+  if (!start) {
+    return roots;
+  }
+  let current = path.resolve(start);
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, ".git")) ||
+      fs.existsSync(path.join(current, ".gitmodules"))
+    ) {
+      roots.push(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return roots;
+}
+
+function parseGitmodules(content) {
+  const modules = [];
+  if (typeof content !== "string" || content.length === 0) {
+    return modules;
+  }
+  let current = null;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const name = line.match(/^\[submodule "(.+)"\]$/);
+    if (name) {
+      current = { name: name[1], path: "", url: "" };
+      modules.push(current);
+      continue;
+    }
+    if (!current) {
+      continue;
+    }
+    const pathMatch = line.match(/^path\s*=\s*(.+)$/);
+    if (pathMatch) {
+      current.path = pathMatch[1].trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    }
+    const urlMatch = line.match(/^url\s*=\s*(.+)$/);
+    if (urlMatch) {
+      current.url = urlMatch[1].trim();
+    }
+  }
+  return modules;
+}
+
+function readGitmodules(repoRoot) {
+  const file = path.join(repoRoot, ".gitmodules");
+  if (!fs.existsSync(file) || pathKind(file) !== "file") {
+    return [];
+  }
+  return parseGitmodules(fs.readFileSync(file, "utf8"));
+}
+
+function gitLsFilesStage(repoRoot, relativePath) {
+  const result = spawnSync(
+    "git",
+    ["-C", repoRoot, "ls-files", "--stage", "--", relativePath],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return null;
+  }
+  const line = (result.stdout || "").trim().split(/\r?\n/).filter(Boolean)[0];
+  if (!line) {
+    return null;
+  }
+  const match = line.match(/^(\d+)\s+([0-9a-f]+)\s+(\d+)\s+(.+)$/i);
+  if (!match) {
+    return null;
+  }
+  return { mode: match[1], sha: match[2], stage: match[3], path: match[4] };
+}
+
+function gitShowSuperproject(cwd) {
+  const result = spawnSync(
+    "git",
+    ["-C", cwd, "rev-parse", "--show-superproject-working-tree"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return "";
+  }
+  return (result.stdout || "").trim();
+}
+
+function gitAbbrevRef(cwd) {
+  const result = spawnSync(
+    "git",
+    ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"],
+    { encoding: "utf8" },
+  );
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim();
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) {
+    return true;
+  }
+  try {
+    return fs.readdirSync(dir).filter((name) => name !== "." && name !== "..")
+      .length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function isGitSubmoduleMount(repoRoot, targetPathValue) {
+  const relative = posixRelative(repoRoot, path.resolve(targetPathValue));
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return false;
+  }
+  if (readGitmodules(repoRoot).some((item) => item.path === relative)) {
+    return true;
+  }
+  const staged = gitLsFilesStage(repoRoot, relative);
+  return staged?.mode === GITLINK_MODE;
+}
+
+function inspectCheckoutState(repoRoot, targetPathValue) {
+  const resolved = path.resolve(targetPathValue);
+  const relative = posixRelative(path.resolve(repoRoot), resolved);
+  const inRepo = Boolean(relative) && !relative.startsWith("..");
+  const staged = inRepo ? gitLsFilesStage(repoRoot, relative) : null;
+  const listed = inRepo
+    ? readGitmodules(repoRoot).some((item) => item.path === relative)
+    : false;
+  const superproject = fs.existsSync(path.join(resolved, ".git"))
+    ? gitShowSuperproject(resolved)
+    : "";
+  const isMount = staged?.mode === GITLINK_MODE || listed || Boolean(superproject);
+  const hasGit = fs.existsSync(path.join(resolved, ".git"));
+  if (isMount && !hasGit) {
+    return isEmptyDir(resolved) ? "empty-gitlink" : "uninitialized";
+  }
+  if (isMount && hasGit) {
+    const ref = gitAbbrevRef(resolved);
+    if (ref === "HEAD") {
+      return "detached-head";
+    }
+    return "attached-branch";
+  }
+  return null;
+}
+
+function gitlinkWriteViolation(targetDir, { force = false } = {}) {
+  const resolved = path.resolve(targetDir);
+  const roots = collectGitRoots(resolved);
+  for (const root of roots) {
+    if (path.resolve(root) === PACKAGE_ROOT) {
+      continue;
+    }
+    let current = resolved;
+    while (true) {
+      if (isGitSubmoduleMount(root, current)) {
+        const checkout = inspectCheckoutState(root, current);
+        if (checkout === "empty-gitlink" || checkout === "uninitialized") {
+          return "空 gitlink 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (checkout === "detached-head") {
+          return "detached HEAD 不得当成普通目录写入；gitlink 不得由 CLI 覆盖";
+        }
+        if (path.resolve(current) === resolved) {
+          return force
+            ? "--force 不得把 git-submodule 挂载点当成普通目录覆盖"
+            : "git-submodule gitlink 不得由 CLI 覆盖；先 git submodule update --init，在子仓附加分支的工作树内操作，或改用独立目录";
+        }
+      }
+      if (path.resolve(current) === path.resolve(root)) {
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+
+function assertTargetWorkingTreeWritable(targetDir, { force = false } = {}) {
+  const violation = gitlinkWriteViolation(targetDir, { force });
+  if (violation) {
+    throw new Error(violation);
+  }
+}
+
+function unmanagedPathReason(targetDir, relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  if (UNMANAGED_USER_PATHS.has(normalized) || normalized.split("/")[0] === ".gitmodules") {
+    return ".gitmodules 是用户资产，不属于受管模板文件";
+  }
+  const absolutePath = path.resolve(targetDir, normalized);
+  const roots = collectGitRoots(targetDir);
+  for (const root of roots) {
+    if (path.resolve(root) === PACKAGE_ROOT) {
+      continue;
+    }
+    let current = absolutePath;
+    while (true) {
+      if (isGitSubmoduleMount(root, current)) {
+        return "gitlink / apps 挂载工作树是用户资产，不属于受管模板文件";
+      }
+      if (path.resolve(current) === path.resolve(root)) {
+        break;
+      }
+      const parent = path.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return null;
+}
+
 function normalizeRelativePath(relativePath) {
   return relativePath.split(path.sep).join("/");
 }
@@ -857,6 +1100,14 @@ function classifyAttachPlan(targetDir, variables) {
   };
 
   for (const operation of desiredOperations) {
+    const unmanagedReason = unmanagedPathReason(targetDir, operation.relativePath);
+    if (unmanagedReason) {
+      plan.unsafe.push({
+        ...operation,
+        reason: unmanagedReason,
+      });
+      continue;
+    }
     const kind = pathKind(operation.targetPath);
     if (kind === "missing") {
       plan.missing.push(operation);
@@ -900,6 +1151,14 @@ function classifySyncPlan(targetDir, metadata, identity = readTargetIdentity(tar
   const unsafe = [];
 
   for (const operation of desiredOperations) {
+    const unmanagedReason = unmanagedPathReason(targetDir, operation.relativePath);
+    if (unmanagedReason) {
+      unsafe.push({
+        ...operation,
+        reason: unmanagedReason,
+      });
+      continue;
+    }
     const existingRecord = managedFiles[operation.relativePath];
     const existingKind = pathKind(operation.targetPath);
 
@@ -1024,6 +1283,8 @@ function inspectTargetDir(targetDir, force) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
 
+  assertTargetWorkingTreeWritable(targetDir, { force });
+
   if (!fs.existsSync(targetDir)) {
     return { exists: false, clearEntries: false };
   }
@@ -1040,13 +1301,14 @@ function inspectTargetDir(targetDir, force) {
   return { exists: true, clearEntries: entries.length > 0 && force };
 }
 
-function inspectExistingTargetDir(targetDir) {
+function inspectExistingTargetDir(targetDir, { force = false } = {}) {
   if (isInsideTemplateRoot(targetDir)) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
   if (!fs.existsSync(targetDir) || pathKind(targetDir) !== "directory") {
     throw new Error("attach 目标目录必须是已经存在的项目目录");
   }
+  assertTargetWorkingTreeWritable(targetDir, { force });
 }
 
 function prepareTargetDir(targetDir, targetState) {
@@ -1126,8 +1388,8 @@ function runTemplateVerification(targetDir, scriptPath) {
 }
 
 function verifyGeneratedTemplate(targetDir, mode = "managed") {
-  if (mode === "init") {
-    verifyGeneratedInstance(targetDir);
+  if (mode === "init" || mode === "sync") {
+    verifyGeneratedInstance(targetDir, { checkForbiddenPaths: mode === "init" });
     return;
   }
 
@@ -1140,15 +1402,18 @@ function verifyGeneratedTemplate(targetDir, mode = "managed") {
   }
 }
 
-function verifyGeneratedInstance(targetDir) {
-  const forbiddenPaths = [
-    ...[...INIT_EXCLUDED_ROOT_ENTRIES],
-    ...[...INIT_EXCLUDED_ROOT_FILES],
-    ...[...INIT_EXCLUDED_RELATIVE_PATHS],
-  ];
-  for (const relativePath of forbiddenPaths) {
-    if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
-      throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+function verifyGeneratedInstance(targetDir, { checkForbiddenPaths = true } = {}) {
+  if (checkForbiddenPaths) {
+    const forbiddenPaths = [
+      ...INSTANCE_FORBIDDEN_PATHS,
+      ...[...INIT_EXCLUDED_ROOT_ENTRIES],
+      ...[...INIT_EXCLUDED_ROOT_FILES],
+      ...[...INIT_EXCLUDED_RELATIVE_PATHS],
+    ];
+    for (const relativePath of [...new Set(forbiddenPaths)]) {
+      if (pathKind(targetPath(targetDir, relativePath)) !== "missing") {
+        throw new Error(`初始化结果包含禁止分发的模板源资产：${relativePath}`);
+      }
     }
   }
 
@@ -1539,6 +1804,10 @@ function runInit(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   return promptForMissingOptions(options).then((promptedOptions) => {
     assertRequiredOptions(promptedOptions, "init");
     readTemplateSnapshot();
@@ -1592,6 +1861,10 @@ function runAttach(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   assertRequiredOptions(options, "attach");
   if (options.dryRun && options.apply) {
     throw new Error("attach 的 --dry-run 与 --apply 互斥");
@@ -1602,7 +1875,7 @@ function runAttach(argv = []) {
 
   readTemplateSnapshot();
   const targetDir = normalizeTargetDir(options.targetDir);
-  inspectExistingTargetDir(targetDir);
+  inspectExistingTargetDir(targetDir, { force: Boolean(options.force) });
   if (pathKind(targetPath(targetDir, TEMPLATE_METADATA_FILENAME)) !== "missing") {
     throw new Error("当前项目已有模板元数据，请使用 sync，不要重复 attach");
   }
@@ -1692,9 +1965,13 @@ function runSync(argv = []) {
     printHelp();
     return;
   }
+  if (options.version) {
+    printVersion();
+    return;
+  }
   readTemplateSnapshot();
   const targetDir = normalizeTargetDir(options.targetDir || ".");
-  inspectExistingTargetDir(targetDir);
+  inspectExistingTargetDir(targetDir, { force: Boolean(options.force) });
   const { metadata } = loadTemplateMetadata(targetDir);
   const identity = readTargetIdentity(targetDir);
   const syncPlan = classifySyncPlan(targetDir, metadata, identity);
@@ -1738,7 +2015,7 @@ function runSync(argv = []) {
       applyManagedOperation(operation, transaction);
     }
     applyMigrationPlan(migrationPlan, transaction);
-    verifyGeneratedTemplate(targetDir, "init");
+    verifyGeneratedTemplate(targetDir, "sync");
     writeTemplateMetadata(
       targetDir,
       buildNextSyncMetadata(metadata, syncPlan, targetDir),
@@ -1782,16 +2059,87 @@ function runSync(argv = []) {
   console.log("3. 确认无误后提交本次模板同步结果");
 }
 
+function argvIncludesFlag(argv, flags) {
+  return argv.some((arg) => flags.has(arg));
+}
+
+function printVersion() {
+  console.log(`create-yss-spec ${PACKAGE_MANIFEST.version}`);
+}
+
 function printHelp() {
   console.log(`create-yss-spec ${PACKAGE_MANIFEST.version}
 
-初始化：create-yss-spec --project-name <name> --business-domain <domain> --target-dir <dir>
-接管已有项目：create-yss-spec attach --target-dir <dir> --project-name <name> --business-domain <domain> --dry-run|--apply [--force]
-同步模板：create-yss-spec sync [--target-dir <dir>] [--dry-run] [--force]
+USAGE
+  $ create-yss-spec [COMMAND] [OPTIONS]
+
+COMMANDS
+  (default)  初始化新的模板实例仓库
+  attach     向已有项目补齐受管研发管理资产
+  sync       同步已有模板实例的受管资产
+
+OPTIONS
+  --project-name <name>              项目名称；init 不传则进入交互输入
+  --business-domain <domain>         业务领域；init 不传则进入交互输入
+  --team-size <size>                 团队规模；init 不传则可留空，默认「待补充」
+  --target-dir <dir>                 目标目录；init 不传则进入交互输入，sync 默认为当前目录
+  --issue-tracker github|gitlab      默认 issue tracker 偏好（默认 github）
+  --dry-run                          只预览计划，不写入文件
+  --apply                            attach 确认执行写入；不能与 --dry-run 同时使用
+  --force                            init：允许清空非空目录后重新生成
+                                     attach / sync：覆盖受管冲突文件；unsafe 路径始终阻断
+  --git-init                         初始化完成后执行 git init
+  --include-example-docs             显式保留示例文档（默认开启）
+  --no-example-docs                  不生成示例文档
+  -h, --help                         显示本帮助信息
+  -v, --version                      显示 CLI 版本
+
+EXAMPLES
+  $ npm create yss-spec@latest
+  $ npx create-yss-spec@latest --help
+  $ npx create-yss-spec@latest --version
+  $ npx create-yss-spec@latest \\
+      --project-name "Acme Spec Repo" \\
+      --business-domain "Investment Research" \\
+      --team-size "12" \\
+      --target-dir "./acme-spec-repo" \\
+      --issue-tracker github \\
+      --git-init
+  $ npx create-yss-spec@latest \\
+      --project-name "Preview Repo" \\
+      --business-domain "Data Platform" \\
+      --target-dir "./preview-repo" \\
+      --dry-run
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --dry-run
+  $ npx create-yss-spec@latest attach \\
+      --target-dir . \\
+      --project-name "Acme Application" \\
+      --business-domain "Data Platform" \\
+      --apply
+  $ npx create-yss-spec@latest sync
+  $ npx create-yss-spec@latest sync --dry-run
+  $ npx create-yss-spec@latest sync --target-dir . --force
+
+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/yss-spec-project-template
 `);
 }
 
 async function runCli(argv = []) {
+  if (argvIncludesFlag(argv, HELP_FLAGS)) {
+    printHelp();
+    return;
+  }
+  if (argvIncludesFlag(argv, VERSION_FLAGS)) {
+    printVersion();
+    return;
+  }
   if (argv[0] === "sync") {
     runSync(argv.slice(1));
     return;

package/template/.agents/skills/cross-repo-implementation-routing/SKILL.md

@@ -19,8 +19,8 @@ description: Use when a Harness change or vertical slice may require work across
 1. 读取 `docs/process/implementation-repo-integration.md` 和当前 change 资产。
 2. 判断影响面：Harness-only、backend-only、frontend-only、backend+frontend、contract-only、release-only。
 3. 确认每个受影响实现仓库已有登记记录；缺失则阻断并要求 onboarding。
-4. 核对项目根路径：Harness 内项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。外部仓库记录各自的真实项目根。
-5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。
+4. 核对项目根路径：Harness 内 `harness-apps` 与 `git-submodule` 项目必须是 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 只能作为容器，`app/backend/`、`app/frontend/` 及其子路径必须阻断。`git-submodule` 另核 gitlink、`.gitmodules` 和独立 `git_url`。外部 `external-repository` 记录各自的真实项目根。
+5. 输出最小任务分配：Harness 文档 / OpenAPI / 后端 MR / 前端 MR / 验证 / 发布。`git-submodule` 必须追加 `superproject-gitlink-update`。
 6. 按 `docs/templates/cross-repo-slice-template.md` 生成切片记录草案。
 7. 给出 fresh verification 命令和阶段 checkpoint 回写字段。
 

package/template/.agents/skills/implementation-repo-onboarding/SKILL.md

@@ -18,11 +18,11 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 
 1. 确认当前仓库是 Harness 仓库，读取 `docs/process/implementation-repo-integration.md`。
 2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
-3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
+3. 如果输入是远端 URL，优先使用只读 Git 查询。需要完整工作树时：`external-repository` 只能 clone 到临时目录；`git-submodule` 只能通过 `git submodule add` / `git submodule update --init` 在已批准的 `apps/backend/<project>/` 或 `apps/frontend/<project>/` gitlink 挂载点检出，禁止普通 clone 或复制源码进 Harness。
 4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
-5. 判定实现位置：Harness 内只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。外部实现仓库记录真实项目根路径，不套用 Harness 占位路径。
-6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
-7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+5. 判定实现位置与 `repository_scope`：`external-repository` 记录真实项目根；`harness-apps` 与 `git-submodule` 只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`。`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。gitlink（mode `160000`）必须登记为 `git-submodule` 和 `layout_policy: git-submodule-harness-apps`，不得写成 `harness-apps`。必须对照工作树：`git ls-files --stage`、`.gitmodules` 与声明 scope 不一致时阻断；缺少 `git_entry_mode: 160000` 不得把挂载点当普通目录。
+6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。`git-submodule` 必填 `gitmodules_name`、`gitlink_path`、`git_entry_mode`、`superproject_git_url` 和 `checkout_state`。`harness-apps` / `external-repository` 这些字段填 `不适用`。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。空 gitlink、detached HEAD、`--force` 覆盖挂载点或缺少递归检出凭据时标记阻断。写入前必须看 `inspectWorkingTreeScope` / `implementationWriteViolation`：只接受对象结果且 `.writable === true` 才可写；字符串、`null` 或 `.writable !== true` 一律不可写。即使已正确登记为 `git-submodule`，空 gitlink 或 detached HEAD 也必须 `.writable === false`，不得当普通目录写文件或脚手架。
 
 ## Baseline Checks
 
@@ -36,7 +36,7 @@ description: Use when connecting an existing frontend, backend, fullstack, or ot
 ## Boundaries
 
 - 不直接提交、推送、创建 MR / PR 或修改实现仓库。
-- 不把实现仓库源码复制进 Harness 仓库。
+- 不把实现仓库源码复制进 Harness 仓库；`git-submodule` 只能形成 gitlink，不能 copy / subtree 冒充。
 - 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
 - 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
 - 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。

package/template/.agents/skills/llm-wiki/SKILL.md

@@ -51,7 +51,7 @@ node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <w
 
 ## Steps
 
-1. Detect: `wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists.
+1. Detect: `<wiki-root>/wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists. Default wiki-root is repo-root `wiki/`. If `yss-project.yaml` is `repository_mode: template-source`, wiki-root is `.template-source/wiki`.
 2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
 3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
 4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).

package/template/.agents/skills/llm-wiki/references/discover.md

@@ -27,6 +27,7 @@ Unless the user replaces this list with the host's single source-of-truth table:
 ## Default exclude
 
 - `docs/reviews/`
+- `.template-source/evidence/`
 - `docs/.scratch/`
 - Agent projection directories (copies or symlinks of shared skills)
 - `node_modules`

package/template/.agents/skills/yss-ddd-scaffold-generator/SKILL.md

@@ -64,7 +64,7 @@ node scripts/generate_scaffold.mjs \
 - 永不生成 `User CRUD` 示例；`--with-example` 已禁用，业务代码必须按批准的 Slice Implementation Contract 逐切片实现。
 - 若仓库已经存在相同工程，先核对覆盖范围。
 - 输出目录必须显式指定；非空目录默认拒绝写入，确认覆盖时才使用 `--force`。
-- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。
+- Harness 内多项目布局必须使用 `apps/backend/<project>/`；`apps/backend/` 只能是生成器的父容器，`app/backend/`、`app/frontend/` 及其子路径一律拒绝。`git-submodule` gitlink、空挂载点、detached HEAD 工作树不得覆盖生成，即使传入 `--force` 也不得当成普通目录，且不得走「请显式传入 `--force`」普通目录覆盖 / rename 路径。`--output-dir` 指向 detached HEAD 子仓时不得 mkdir、staging 或生成工程。先 `git submodule update --init` 并在子仓附加分支工作树内生成。生成器必须先调用 `gitSubmoduleScaffoldViolation`，再在 exists / `--force` / rename 之前调用 `refuseGitlinkAsRegularDirectory`。
 - 不要在 skill 里硬编码用户业务字段或真实连接信息。
 - 生成后要检查依赖关系是否仍符合分层约束。
 - 生成后必须继续使用 `yss-backend-scaffold-parent` 校验工程基线，再按垂直切片加载 `yss-domain`、`yss-application`、`yss-repository`、`yss-web-controller` 等行为 skill；各 skill 的 `references/*-layer-guide.md` 承载分层开发规范。