create-yss-spec 2.1.15 → 2.2.0

package/README.md

@@ -44,8 +44,10 @@ npx create-yss-spec@latest --version
 - 接管 / 升级时迁移 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.15` 发布。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
+本次模板适配按 `2.2.0` 发布，绑定 `yss-spec-project-template@04a6151`。`templateCommit` 会写入实例 metadata；“最新模板”指用户执行的 `npx create-yss-spec@latest` 所携带的最新已发布快照，CLI 运行时不会拉取模板仓库。
 
 ## 接管已有项目
 
@@ -72,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` 也阻断。
 
 ## 同步已有模板实例仓库
 
@@ -96,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.15",
+  "version": "2.2.0",
   "description": "Initialize a YSS spec project template repository",
   "repository": {
     "type": "git",

package/src/cli.js

@@ -39,11 +39,21 @@ 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"],
@@ -301,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("/");
 }
@@ -861,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);
@@ -904,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);
 
@@ -1028,6 +1283,8 @@ function inspectTargetDir(targetDir, force) {
     throw new Error("目标目录不能位于模板源仓库内部");
   }
 
+  assertTargetWorkingTreeWritable(targetDir, { force });
+
   if (!fs.existsSync(targetDir)) {
     return { exists: false, clearEntries: false };
   }
@@ -1044,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) {
@@ -1130,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;
   }
 
@@ -1144,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}`);
+      }
     }
   }
 
@@ -1614,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");
   }
@@ -1710,7 +1971,7 @@ function runSync(argv = []) {
   }
   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);
@@ -1754,7 +2015,7 @@ function runSync(argv = []) {
       applyManagedOperation(operation, transaction);
     }
     applyMigrationPlan(migrationPlan, transaction);
-    verifyGeneratedTemplate(targetDir, "init");
+    verifyGeneratedTemplate(targetDir, "sync");
     writeTemplateMetadata(
       targetDir,
       buildNextSyncMetadata(metadata, syncPlan, targetDir),

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` 承载分层开发规范。

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -5,6 +5,12 @@ import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
 
+import {
+  findGitRoot,
+  gitSubmoduleScaffoldViolation,
+  overlayMountViolation
+} from "../../../../scripts/lib/repository-scope-policy.mjs";
+
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
 const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
@@ -87,11 +93,28 @@ class ScaffoldGenerator {
     this.scaffoldContract = undefined;
   }
 
+  gitRootForOutput() {
+    return findGitRoot(this.finalProjectRoot) || findGitRoot(this.outputDir) || REPOSITORY_ROOT;
+  }
+
+  refuseGitlinkAsRegularDirectory(gitRoot, target) {
+    const overlay = overlayMountViolation(gitRoot, target, { force: true });
+    if (overlay) fail(overlay);
+  }
+
   async generate() {
     await this.validateHarnessOutputLayout();
-    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    const gitRoot = this.gitRootForOutput();
+    const gitlinkViolation = gitSubmoduleScaffoldViolation(gitRoot, this.outputDir, this.projectName, { force: this.options.force });
+    if (gitlinkViolation) fail(gitlinkViolation);
+    this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+    const targetExists = await exists(this.finalProjectRoot);
+    if (targetExists) {
+      this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+      if (!this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    }
     await this.validateContractMetadata();
-    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    if (targetExists && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
     await mkdir(this.outputDir, { recursive: true });
     const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
     this.projectRoot = path.join(stagingRoot, this.projectName);
@@ -101,7 +124,11 @@ class ScaffoldGenerator {
       this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
       await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
       let backupPath;
-      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      if (await exists(this.finalProjectRoot)) {
+        this.refuseGitlinkAsRegularDirectory(gitRoot, this.finalProjectRoot);
+        backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`);
+        await rename(this.finalProjectRoot, backupPath);
+      }
       await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
       console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
       if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);

package/template/.agents/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -1,11 +1,14 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath } from "node:url";
 import { run } from "./run_scaffold_verification.mjs";
+import { makeGitlinkFixture } from "../../../../scripts/lib/git-submodule-fixtures.mjs";
+import { GITLINK_MODE, gitLsFilesStage } from "../../../../scripts/lib/repository-scope-policy.mjs";
 
 const scripts = path.dirname(fileURLToPath(import.meta.url));
 const generator = path.join(scripts, "generate_scaffold.mjs");
@@ -21,6 +24,55 @@ test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t
 
 test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
 
+test("拒绝覆盖 .gitmodules 登记的 git-submodule 挂载点", async (t) => {
+  const data = await fixture();
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  const superproject = path.join(data.root, "harness");
+  const output = path.join(superproject, "apps/backend");
+  await mkdir(path.join(output, "demo-service"), { recursive: true });
+  await writeFile(path.join(superproject, ".gitmodules"), "[submodule \"demo-service\"]\n\tpath = apps/backend/demo-service\n\turl = https://example.invalid/demo-service.git\n");
+  const contractFile = path.join(data.root, "gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  assert.equal(result.code, 1, result.stderr);
+  assert.match(`${result.stdout}\n${result.stderr}`, /gitlink 不得由脚手架覆盖/);
+});
+
+test("拒绝在 detached HEAD 子仓工作树内当成普通目录生成", async (t) => {
+  const data = await fixture();
+  const detached = makeGitlinkFixture({ checkout: "detached-head" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => detached.cleanup());
+  const output = path.join(detached.superproject, detached.mount);
+  const contractFile = path.join(data.root, "detached-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "nested-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /detached HEAD 不得当成普通目录写入/);
+  assert.equal(existsSync(path.join(output, "nested-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("staging") || name === "nested-service"), false);
+});
+
+test("--force 覆盖真实 gitlink 不得走普通目录覆盖路径", async (t) => {
+  const data = await fixture();
+  const empty = makeGitlinkFixture({ checkout: "empty-gitlink" });
+  t.after(() => rm(data.root, { recursive: true, force: true }));
+  t.after(() => empty.cleanup());
+  const output = path.join(empty.superproject, "apps/backend");
+  const contractFile = path.join(data.root, "empty-gitlink-contract.json");
+  await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`);
+  const result = await command(["--project-name", "billing-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]);
+  const text = `${result.stdout}\n${result.stderr}`;
+  assert.equal(result.code, 1, text);
+  assert.doesNotMatch(text, /请显式传入 --force/);
+  assert.match(text, /--force 不得把 git-submodule 挂载点当成普通目录覆盖|gitlink 不得/);
+  assert.equal(existsSync(path.join(output, "billing-service", "pom.xml")), false);
+  assert.equal((await readdir(output)).some((name) => name.includes("backup")), false);
+  assert.equal(gitLsFilesStage(empty.superproject, empty.mount)?.mode, GITLINK_MODE);
+});
+
 test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
 
 test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });

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

@@ -31,7 +31,7 @@ branch: template
 ## Workflow
 
 1. 确认当前任务已经通过 Harness 入口分诊，且实现位置已记录在 proposal、design、build entry review、实施计划或实现路由记录中。
-2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。
+2. 确认目标是外部实现仓库；只有用户明确选择时才输出到 Harness 仓库的 `apps/frontend/<project>/`。`apps/frontend/` 只能作为项目容器，`app/frontend/`、`app/backend/` 及其子路径禁止作为输出位置。`git-submodule` 只能在已初始化且附加分支的子仓工作树生成；空 gitlink、detached HEAD、`--force` 覆盖挂载点不得当成普通目录。
 3. 只读检查模板分支是否可访问：`git ls-remote --heads <repo> template`。
 4. 需要生成工程时，克隆或复制模板到用户确认的目标位置；不得默认写入 Harness 仓库。
 5. 替换应用名、微应用名、路由、`micro-config.json`、环境变量和 README 中的模板占位。

package/template/.agents/skills/yss-product-lifecycle/references/matt-yss-adapter.md

@@ -78,7 +78,7 @@ Router 状态映射为：`draft → completed`、`blocked → blocked`、`ready-
 
 YSS 调用 `code-review` 前必须形成 review input，至少包含 `review_mode`、`review_base_ref`、`implementation_candidate_ref`、`candidate_snapshot_ref`、`candidate_digest`、`spec_ref`、`ticket_ref`、`slice_contract_ref`、`build_architecture_checklist_ref` 和 `yss_execution_result_refs`，并满足 `orchestration-contract.yaml.review_input.manifest_required_by_mode`。`committed` 审查 merge-base 到不可变 `HEAD`；`worktree` 一次捕获 merge-base 到 working tree 的 committed、staged、unstaged 和 untracked 内容，使用 `yss-worktree-candidate-v1` 规定的 raw path、uint64 big-endian 长度、tracked/untracked record 和不支持条目阻断规则计算 SHA-256，让两个 Reviewer 消费同一不可变快照，并在返回和完成 checkpoint 复核摘要未变化。缺少输入、候选为空或摘要变化时返回 `blocked`，不能缩小审查范围或合并不同候选的结论。
 
-Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。
+Matt `implement` 的通用提交指令不构成 YSS Git 授权。只有用户明确给出 `commit_authorized` 为 `true`、非空 `commit_scope` 和 `commit_authorization_ref` 时才能 commit；只有明确给出 `push_authorized` 为 `true`、非空 `push_scope` 和 `push_authorization_ref` 时才能 push。缺少任一字段时保持工作区不变，只输出 checkpoint 判断；不得把 `orchestrate`、实现授权、当前分支、测试通过或负责人要求解释为隐含授权。`git-submodule` 还必须按仓授权、禁止 detached HEAD 提交，并先推子仓再更新父仓 gitlink。
 
 “然后 commit”“做完提交”“可以帮我提交”等自然语言意向本身不是结构化授权。编排器必须取得上述三个 commit 字段；不能先把意向解释成授权，再在完成时补 scope 或引用。