create-yss-spec 2.1.15 → 2.2.1

package/template/scripts/lib/skill-registry.mjs

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { parseDocument } from "../vendor/yaml.mjs";
 import { PROJECTION_ROOTS, ROOT } from "./skill-supply-chain.mjs";
@@ -6,9 +6,11 @@ import { PROJECTION_ROOTS, ROOT } from "./skill-supply-chain.mjs";
 export const DEFAULT_REGISTRY = path.join(ROOT, "docs/agents/yss-skill-registry.yaml");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const ROUTER_CONTRACT = path.join(ROOT, ".agents/skills/yss-router/references/router-contract.yaml");
+const LIFECYCLE_CONTRACT = path.join(ROOT, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml");
 const LAYERS = new Set(["core", "specialist", "compatibility", "maintainer-only"]);
 const MATURITIES = new Set(["draft", "verified", "supported", "deprecated"]);
 const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const PLATFORM_ALIAS_PATTERN = /^[a-z0-9][a-z0-9-]*(?::[a-z0-9][a-z0-9-]*)?$/;
 
 function fail(message) {
   throw new TypeError(message);
@@ -45,7 +47,7 @@ function requireString(value, field) {
   if (typeof value !== "string" || !value.trim()) fail(`${field} 不能为空`);
 }
 
-export function validateSkillRegistry(registry, { lock, routerContract, skillSource } = {}) {
+export function validateSkillRegistry(registry, { lock, routerContract, lifecycleContract, skillSource } = {}) {
   if (!registry || typeof registry !== "object" || Array.isArray(registry)) fail("技能路由注册表必须是对象");
   if (registry.schema_version !== 1) fail("schema_version 必须为 1");
   if (registry.registry_id !== "yss.skill-routing") fail("registry_id 必须为 yss.skill-routing");
@@ -99,10 +101,14 @@ export function validateSkillRegistry(registry, { lock, routerContract, skillSou
     if (!MATURITIES.has(skill.maturity)) fail(`${skill.id} 未知 maturity: ${skill.maturity}`);
     if (typeof skill.instance_default_discoverable !== "boolean") fail(`${skill.id} 缺少 instance_default_discoverable`);
     if (skill.layer === "core" && skill.instance_default_discoverable !== true) fail(`${skill.id} 作为 core 必须默认可发现`);
-    if ((skill.layer === "specialist" || skill.layer === "maintainer-only") && skill.instance_default_discoverable !== false) {
+    if (["specialist", "maintainer-only", "compatibility"].includes(skill.layer) && skill.instance_default_discoverable !== false) {
       fail(`${skill.id} 作为 ${skill.layer} 不得默认可发现`);
     }
-    if (skill.maturity === "deprecated") requireString(skill.replaced_by, `${skill.id}.replaced_by`);
+    if (skill.maturity === "deprecated") {
+      requireString(skill.replaced_by, `${skill.id}.replaced_by`);
+      requireString(skill.migration_deadline, `${skill.id}.migration_deadline`);
+      requireString(skill.cleanup_status, `${skill.id}.cleanup_status`);
+    }
     if (skill.replaced_by && !ids.has(skill.replaced_by) && !skills.some((item) => item.id === skill.replaced_by)) {
       // resolved in second pass
     }
@@ -125,6 +131,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, skillSou
   const platform = registry.platform_skills ?? [];
   if (!Array.isArray(platform)) fail("platform_skills 必须是数组");
   const platformIds = new Set();
+  const platformAliases = new Map();
   for (const skill of platform) {
     requireString(skill.id, "platform_skills.id");
     requireString(skill.root, `${skill.id}.root`);
@@ -132,9 +139,27 @@ export function validateSkillRegistry(registry, { lock, routerContract, skillSou
     if (typeof skill.instance_default_discoverable !== "boolean" || skill.instance_default_discoverable !== false) {
       fail(`${skill.id} 平台技能不得作为实例默认可发现`);
     }
+    if (!Array.isArray(skill.aliases) || skill.aliases.some((alias) => typeof alias !== "string" || !PLATFORM_ALIAS_PATTERN.test(alias))) {
+      fail(`${skill.id} aliases 必须是合法 id 数组`);
+    }
     if (platformIds.has(`${skill.root}:${skill.id}`)) fail(`重复平台技能: ${skill.root}/${skill.id}`);
     platformIds.add(`${skill.root}:${skill.id}`);
   }
+  const external = registry.external_skills ?? [];
+  if (!Array.isArray(external)) fail("external_skills 必须是数组");
+  const externalIds = new Set();
+  for (const skill of external) {
+    requireString(skill.id, "external_skills.id");
+    requireString(skill.source, `${skill.id}.source`);
+    if (externalIds.has(skill.id) || ids.has(skill.id) || aliases.has(skill.id) || platformAliases.has(skill.id)) fail(`external skill 冲突: ${skill.id}`);
+    externalIds.add(skill.id);
+  }
+  for (const skill of platform) {
+    for (const alias of skill.aliases) {
+      if (ids.has(alias) || aliases.has(alias) || platformAliases.has(alias)) fail(`alias 冲突: ${alias}`);
+      platformAliases.set(alias, `${skill.root}:${skill.id}`);
+    }
+  }
 
   if (lock) {
     const shared = Object.keys(lock.skills?.shared ?? {}).sort();
@@ -179,7 +204,58 @@ export function validateSkillRegistry(registry, { lock, routerContract, skillSou
     }
     const closures = Object.keys(routerContract.dependency_closure ?? {});
     for (const name of closures) {
-      if (!ids.has(name) && !aliases.has(name)) fail(`Router 闭包引用了未登记技能: ${name}`);
+      if (!ids.has(name) && !aliases.has(name) && !externalIds.has(name)) fail(`Router 闭包引用了未登记技能: ${name}`);
+    }
+    for (const dependencies of Object.values(routerContract.dependency_closure ?? {})) {
+      for (const names of Object.values(dependencies ?? {})) {
+        for (const name of names ?? []) if (!ids.has(name) && !aliases.has(name) && !externalIds.has(name)) fail(`Router 依赖引用了未登记技能: ${name}`);
+      }
+    }
+  }
+
+  if (lifecycleContract || existsSync(LIFECYCLE_CONTRACT)) {
+    const lifecycle = lifecycleContract ?? yamlFromFile(LIFECYCLE_CONTRACT, "生命周期编排合同");
+    const routes = lifecycle.work_unit_routes;
+    if (!routes || typeof routes !== "object" || Array.isArray(routes)) fail("生命周期编排合同缺少 work_unit_routes");
+    const resolve = (name) => {
+      if (ids.has(name)) return name;
+      if (aliases.has(name)) return aliases.get(name);
+      if (platformAliases.has(name)) return platformAliases.get(name);
+      if (externalIds.has(name)) return name;
+      if ([...platformIds].some((key) => key.endsWith(`:${name}`))) return name;
+      return null;
+    };
+    for (const [routeId, route] of Object.entries(routes)) {
+      if (!route || typeof route !== "object") fail(`${routeId} 生命周期路由必须是对象`);
+      requireString(route.primary_skill, `${routeId}.primary_skill`);
+      if (!Array.isArray(route.supporting_skills)) fail(`${routeId}.supporting_skills 必须是数组`);
+      if (!Array.isArray(route.skills) || route.skills.length === 0) fail(`${routeId}.skills 不能为空`);
+      if (!route.applies_when || !route.not_applicable_reason) fail(`${routeId} 缺少 applies_when 或 not_applicable_reason`);
+      for (const name of [route.primary_skill, ...route.supporting_skills, ...route.skills]) {
+        if (!resolve(name)) fail(`生命周期路由引用了未登记技能: ${routeId} -> ${name}`);
+      }
+      if (route.frontend_route) {
+        requireString(route.frontend_route.primary_skill, `${routeId}.frontend_route.primary_skill`);
+        requireString(route.frontend_route.page_orchestration_skill, `${routeId}.frontend_route.page_orchestration_skill`);
+        const conditional = route.frontend_route.conditional_skills;
+        if (!conditional || typeof conditional !== "object" || Array.isArray(conditional)) fail(`${routeId}.frontend_route.conditional_skills 必须是对象`);
+        for (const [impact, names] of Object.entries(conditional)) {
+          if (!Array.isArray(names) || names.length === 0) fail(`${routeId}.frontend_route.conditional_skills.${impact} 必须是非空数组`);
+          for (const name of names) if (!resolve(name)) fail(`前端条件路由引用了未登记技能: ${routeId}.${impact} -> ${name}`);
+          if (route.frontend_route.not_applicable_reasons && typeof route.frontend_route.not_applicable_reasons[impact] !== "string") {
+            fail(`${routeId}.frontend_route.not_applicable_reasons.${impact} 必须是字符串`);
+          }
+        }
+        if (!resolve(route.frontend_route.primary_skill) || !resolve(route.frontend_route.page_orchestration_skill)) {
+          fail(`${routeId}.frontend_route 主入口引用了未登记技能`);
+        }
+      }
+      if (routeId === "work-unit.prototype-design") {
+        if (!route.skills.includes("prototype-review") || !route.supporting_skills.includes("prototype-review")) {
+          fail("原型工作单元必须包含独立 prototype-review supporting skill");
+        }
+        if (route.primary_skill === "prototype-review") fail("prototype-review 必须作为独立 supporting skill，不得成为生命周期主技能");
+      }
     }
   }
 
@@ -193,6 +269,7 @@ export function validateDefaultSkillRegistry() {
   return validateSkillRegistry(registry, {
     lock,
     routerContract,
+    lifecycleContract: yamlFromFile(LIFECYCLE_CONTRACT, "生命周期编排合同"),
     skillSource: (id) => readFileSync(path.join(ROOT, ".agents/skills", id, "SKILL.md"), "utf8")
   });
 }

package/template/scripts/lib/skill-supply-chain.mjs

@@ -49,6 +49,10 @@ export function unlockedProjectionEntries(candidates, allowedNames, isTracked) {
   const allowed = new Set(allowedNames);
   return candidates.filter((candidate) => candidate.isDirectory() || candidate.isSymbolicLink()).filter((candidate) => !allowed.has(candidate.name) && isTracked(candidate.name));
 }
+export function unlockedCanonicalEntries(names, allowedNames, hasSkillMd = () => true) {
+  const allowed = new Set(allowedNames);
+  return names.filter((name) => !allowed.has(name) && !OBSOLETE.has(name) && hasSkillMd(name)).sort();
+}
 export function syncSkills({ check = false } = {}) {
   const lock = parseLock();
   const shared = sharedFromLock(lock);
@@ -141,7 +145,7 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   const sharedNames = [...new Set([...existing, ...additions])].filter((name) => !removals.has(name) && !OBSOLETE.has(name)).sort();
   const absent = sharedNames.filter((name) => !lstatSafe(path.join(SOURCE_ROOT, name))?.isDirectory());
   if (absent.length) throw new TypeError(`锁文件声明的共享 skills 缺少权威内容: ${absent.join(", ")}`);
-  const unlocked = skillNames(SOURCE_ROOT).filter((name) => tracked(`.agents/skills/${name}`) && !sharedNames.includes(name) && !OBSOLETE.has(name));
+  const unlocked = unlockedCanonicalEntries(skillNames(SOURCE_ROOT), sharedNames, (name) => lstatSafe(path.join(SOURCE_ROOT, name, "SKILL.md"))?.isFile());
   if (unlocked.length) throw new TypeError(`发现未登记到 skills-lock.json 的已跟踪共享 skills: ${unlocked.join(", ")}\n确认新增后运行 scripts/update-skill-lock --add=<skill-name>`);
   const targets = [".agents/skills", ...PROJECTION_ROOTS];
   const shared = Object.fromEntries(sharedNames.map((name) => {

package/template/scripts/repository-scope-policy

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+export {
+  REPOSITORY_SCOPES as scopes,
+  LAYOUT_POLICIES as layoutPolicies,
+  GITLINK_MODE as gitlinkMode,
+  NAMED_STRESS_SCENARIOS as namedStressScenarios,
+  violationRepositoryScope as violation,
+  validRepositoryScope as valid,
+  gitSubmoduleScaffoldViolation as scaffoldViolation,
+  isGitSubmoduleMount as isMount,
+  inspectWorkingTree as inspectWorkingTree,
+  inspectCheckoutState as inspectCheckout,
+  isWorkingTreeWritable as isWorkingTreeWritable,
+  regularDirectoryMisreadViolation as regularDirectoryMisread,
+  implementationWriteViolation as writeViolation
+} from "./lib/repository-scope-policy.mjs";

package/template/scripts/verify-repository-scope-scenarios

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  LAYOUT_POLICIES,
+  NAMED_STRESS_SCENARIOS,
+  REPOSITORY_SCOPES,
+  gitSubmoduleCommitViolation,
+  gitSubmodulePushOrderViolation,
+  gitSubmoduleScaffoldViolation,
+  implementationWriteViolation,
+  inspectCheckoutState,
+  inspectWorkingTreeScope,
+  isWorkingTreeWritable,
+  regularDirectoryMisreadViolation,
+  validRepositoryScope,
+  violationRepositoryScope
+} from "./lib/repository-scope-policy.mjs";
+import { makeGitlinkFixture } from "./lib/git-submodule-fixtures.mjs";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const read = (relative) => readFileSync(path.join(root, relative), "utf8");
+const failures = [];
+const namedPassed = [];
+
+function ensure(condition, message) {
+  if (!condition) failures.push(message);
+}
+
+function namedStress(id, condition, message) {
+  if (!NAMED_STRESS_SCENARIOS.includes(id)) {
+    failures.push(`named stress ${id}: unknown id`);
+    return;
+  }
+  if (!condition) {
+    failures.push(`named stress ${id}: FAIL ${message}`);
+    return;
+  }
+  namedPassed.push(id);
+}
+
+const validGitSubmodule = {
+  repository_scope: "git-submodule",
+  layout_policy: LAYOUT_POLICIES["git-submodule"],
+  project_root: "apps/backend/billing-service/",
+  gitlink_path: "apps/backend/billing-service",
+  git_entry_mode: "160000",
+  git_url: "https://example.invalid/billing-service.git",
+  gitmodules_name: "backend-billing-service",
+  superproject_git_url: "https://example.invalid/harness.git",
+  checkout_state: "attached-branch",
+  scaffold_status: "existing"
+};
+
+ensure(validRepositoryScope({ repository_scope: "external-repository", layout_policy: "external-repository-native", project_root: "src/" }), "应允许 external-repository");
+ensure(validRepositoryScope({ repository_scope: "harness-apps", layout_policy: "harness-apps-multi-project", project_root: "apps/frontend/console/" }), "应允许 harness-apps");
+ensure(validRepositoryScope(validGitSubmodule), `应允许正式 git-submodule: ${violationRepositoryScope(validGitSubmodule) ?? ""}`);
+
+namedStress(
+  "unknown_scope",
+  violationRepositoryScope({ repository_scope: "monorepo" })?.includes("repository_scope must be one of"),
+  "未知 repository_scope 应阻断"
+);
+namedStress(
+  "layout_mismatch",
+  violationRepositoryScope({ ...validGitSubmodule, layout_policy: "harness-apps-multi-project" })?.includes("layout_policy"),
+  "git-submodule 不得套用 harness-apps layout_policy"
+);
+namedStress(
+  "same_origin_url",
+  violationRepositoryScope({ ...validGitSubmodule, git_url: validGitSubmodule.superproject_git_url })?.includes("differ"),
+  "子仓 url 不得等于 superproject"
+);
+namedStress(
+  "copy_source_into_harness",
+  violationRepositoryScope({ ...validGitSubmodule, copy_source_into_harness: true })?.includes("gitlink mount"),
+  "复制源码进 Harness 应阻断"
+);
+namedStress(
+  "missing_git_entry_mode",
+  violationRepositoryScope({ ...validGitSubmodule, git_entry_mode: "" })?.includes("git_entry_mode must be 160000"),
+  "git-submodule 缺少 git_entry_mode 应阻断"
+);
+
+ensure(violationRepositoryScope({
+  repository_scope: "harness-apps",
+  layout_policy: "harness-apps-multi-project",
+  project_root: "apps/backend/billing-service/",
+  git_entry_mode: "160000"
+})?.includes("git-submodule"), "harness-apps 记录 gitlink 应改登记为 git-submodule");
+ensure(violationRepositoryScope({
+  repository_scope: "harness-apps",
+  layout_policy: "harness-apps-multi-project",
+  project_root: "apps/backend/billing-service/",
+  gitlink_path: "apps/backend/billing-service",
+  gitmodules_name: "backend-billing-service"
+})?.includes("git-submodule identity"), "harness-apps 填写 gitlink 身份字段应阻断");
+ensure(violationRepositoryScope({ repository_scope: "external-repository", gitlink_path: "apps/backend/billing-service", git_entry_mode: "160000" })?.includes("git-submodule"), "external-repository 挂 apps/ gitlink 应阻断");
+ensure(violationRepositoryScope({ ...validGitSubmodule, checkout_state: "detached-head", commit_allowed: true })?.includes("detached HEAD"), "detached HEAD 提交应阻断");
+ensure(violationRepositoryScope({ ...validGitSubmodule, checkout_state: "detached-head", scaffold_status: "required" })?.includes("regular directory"), "detached HEAD 脚手架应阻断");
+ensure(violationRepositoryScope({ ...validGitSubmodule, checkout_state: "empty-gitlink", scaffold_status: "required" })?.includes("empty or uninitialized"), "空 gitlink 脚手架应阻断");
+ensure(gitSubmoduleCommitViolation({ checkout_state: "detached-head", commit_authorized: true })?.includes("attached branch"), "commit 辅助校验应拒绝 detached HEAD");
+ensure(gitSubmodulePushOrderViolation(["superproject-gitlink", "submodule-repositories"])?.includes("submodule-repositories then superproject-gitlink"), "先父后子 push 应阻断");
+ensure(gitSubmodulePushOrderViolation(["submodule-repositories", "superproject-gitlink"]) === null, "先子后父顺序应允许");
+
+const emptyGitlink = makeGitlinkFixture({ checkout: "empty-gitlink" });
+const detached = makeGitlinkFixture({ checkout: "detached-head" });
+const attached = makeGitlinkFixture({ checkout: "attached-branch" });
+try {
+  const emptyTarget = path.join(emptyGitlink.superproject, emptyGitlink.mount);
+  const emptyRecord = {
+    repository_scope: "git-submodule",
+    project_root: "apps/backend/billing-service/",
+    checkout_state: "empty-gitlink"
+  };
+  const emptyInspection = inspectWorkingTreeScope(emptyGitlink.superproject, emptyRecord);
+  namedStress(
+    "empty_gitlink_as_regular_dir",
+    typeof emptyInspection === "object"
+      && emptyInspection !== null
+      && Array.isArray(emptyInspection) === false
+      && emptyInspection.writable === false
+      && emptyInspection.writable === true === false
+      && isWorkingTreeWritable(emptyInspection) === false
+      && emptyInspection.violation?.includes("regular directory")
+      && inspectCheckoutState(emptyGitlink.superproject, emptyTarget) === "empty-gitlink"
+      && implementationWriteViolation(emptyGitlink.superproject, path.join(emptyTarget, "src/Foo.java"))?.includes("普通目录写入")
+      && gitSubmoduleScaffoldViolation(emptyGitlink.superproject, path.join(emptyGitlink.superproject, "apps/backend"), "billing-service")?.includes("gitlink 不得由脚手架覆盖"),
+    "空 gitlink 仍被当成普通目录"
+  );
+  namedStress(
+    "declared_harness_apps_actual_gitlink",
+    inspectWorkingTreeScope(emptyGitlink.superproject, {
+      repository_scope: "harness-apps",
+      project_root: "apps/backend/billing-service/"
+    }).writable === false
+      && inspectWorkingTreeScope(emptyGitlink.superproject, {
+        repository_scope: "harness-apps",
+        project_root: "apps/backend/billing-service/"
+      }).violation?.includes("不得登记为 harness-apps"),
+    "声明 harness-apps 但工作树是 gitlink 应阻断"
+  );
+  const detachedTarget = path.join(detached.superproject, detached.mount);
+  const detachedInspection = inspectWorkingTreeScope(detached.superproject, {
+    repository_scope: "git-submodule",
+    project_root: "apps/backend/billing-service/",
+    checkout_state: "detached-head"
+  });
+  namedStress(
+    "detached_head_as_regular_dir",
+    detachedInspection.writable === false
+      && inspectCheckoutState(detached.superproject, detachedTarget) === "detached-head"
+      && detachedInspection.violation?.includes("regular directory")
+      && implementationWriteViolation(detached.superproject, path.join(detachedTarget, "nested-service"))?.includes("普通目录写入")
+      && gitSubmoduleScaffoldViolation(detached.superproject, detachedTarget, "nested-service")?.includes("gitlink 不得由脚手架覆盖"),
+    "detached HEAD 仍被当成普通目录"
+  );
+  namedStress(
+    "force_overlay_mount",
+    gitSubmoduleScaffoldViolation(
+      emptyGitlink.superproject,
+      path.join(emptyGitlink.superproject, "apps/backend"),
+      "billing-service",
+      { force: true }
+    )?.includes("--force")
+      && regularDirectoryMisreadViolation(validGitSubmodule, { force: true })?.includes("--force"),
+    "--force 仍可覆盖 gitlink 挂载点"
+  );
+  const attachedNested = path.join(attached.superproject, attached.mount);
+  const attachedInspection = inspectWorkingTreeScope(attached.superproject, {
+    ...validGitSubmodule,
+    checkout_state: "attached-branch"
+  });
+  ensure(
+    inspectCheckoutState(attached.superproject, attachedNested) === "attached-branch",
+    "附加分支 fixture 应处于 attached-branch"
+  );
+  ensure(attachedInspection.writable === true, "附加分支 git-submodule 工作树应可写");
+  ensure(attachedInspection.violation === null, "附加分支工作树对照不应返回 violation");
+  ensure(typeof emptyInspection === "object" && emptyInspection !== null && Array.isArray(emptyInspection) === false, "inspectWorkingTreeScope 必须返回对象，不得返回字符串");
+  ensure(
+    inspectWorkingTreeScope(emptyGitlink.superproject, {
+      ...validGitSubmodule,
+      checkout_state: "empty-gitlink"
+    }).writable === false,
+    "已登记为空 gitlink 的 git-submodule 不得返回可写"
+  );
+  const failedProbe = inspectWorkingTreeScope(process.cwd(), {
+    ...validGitSubmodule,
+    checkout_state: "empty-gitlink"
+  });
+  ensure(typeof failedProbe === "object" && failedProbe !== null, "探测失败时仍须返回对象，不得返回字符串");
+  ensure(failedProbe.writable === false && isWorkingTreeWritable(failedProbe) === false, "登记为空 gitlink 时即使工作树探测失败也不得返回可写");
+  ensure(
+    implementationWriteViolation(attached.superproject, path.join(attachedNested, "src")) === null,
+    "附加分支工作树内写入不应被当成空 gitlink / detached HEAD"
+  );
+  ensure(
+    gitSubmoduleScaffoldViolation(attached.superproject, attachedNested, "nested-service") === null,
+    "附加分支子仓工作树内生成应允许"
+  );
+} finally {
+  emptyGitlink.cleanup();
+  detached.cleanup();
+  attached.cleanup();
+}
+
+for (const id of NAMED_STRESS_SCENARIOS) {
+  if (!namedPassed.includes(id)) failures.push(`named stress ${id}: missing`);
+}
+
+const markerFiles = [
+  ["docs/process/implementation-repo-integration.md", "repository_scope: git-submodule"],
+  ["docs/templates/implementation-repo-registry-template.md", "git-submodule"],
+  ["docs/templates/implementation-repo-registry-template.md", "git-submodule-harness-apps"],
+  ["docs/templates/cross-repo-slice-template.md", "superproject-gitlink-update"],
+  ["docs/templates/implementation-routing-template.md", "git-submodule-harness-apps"],
+  [".agents/skills/implementation-repo-onboarding/SKILL.md", "git-submodule"],
+  [".agents/skills/yss-router/references/slice-implementation-contract.md", "git-submodule-harness-apps"],
+  [".agents/skills/yss-router/references/router-contract.yaml", "git-submodule-harness-apps"],
+  [".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml", "repository_scope=git-submodule"],
+  [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", "gitSubmoduleScaffoldViolation"],
+  [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", "refuseGitlinkAsRegularDirectory"]
+];
+for (const [file, marker] of markerFiles) {
+  ensure(existsSync(path.join(root, file)), `缺少场景资产: ${file}`);
+  ensure(read(file).includes(marker), `场景资产缺少标记 ${marker}: ${file}`);
+}
+
+ensure(REPOSITORY_SCOPES.includes("git-submodule"), "REPOSITORY_SCOPES 必须包含 git-submodule");
+
+if (failures.length > 0) {
+  process.stderr.write(`${failures.join("\n")}\n`);
+  process.exitCode = 1;
+} else {
+  process.stdout.write(`${namedPassed.map((id) => `named stress ${id}: PASS`).join("\n")}\n`);
+  process.stdout.write("实现仓库 repository_scope 压力场景验证通过\n");
+}

package/template/scripts/verify-scaffold-generator-scenarios

@@ -430,6 +430,60 @@ def main() -> int:
             "批准覆盖的备份必须保留原目录内容",
         )
 
+        gitlink_root = temp_root / "gitlink-superproject"
+        gitlink_backend = gitlink_root / "apps" / "backend"
+        gitlink_project = gitlink_backend / "gitlink-service"
+        gitlink_project.mkdir(parents=True)
+        (gitlink_root / ".gitmodules").write_text(
+            '[submodule "backend-gitlink-service"]\n'
+            "\tpath = apps/backend/gitlink-service\n"
+            "\turl = https://example.invalid/gitlink-service.git\n",
+            encoding="utf-8",
+        )
+        gitlink_contract = temp_root / "gitlink-contract.json"
+        write_contract(
+            gitlink_contract,
+            gitlink_backend,
+            "gitlink-service",
+            "backend-scaffold-gitlink",
+            "lifecycle/approval-gitlink",
+            "router/draft-gitlink",
+            "lifecycle/contracts/backend-scaffold-gitlink.yaml",
+            force_allowed=True,
+        )
+        gitlink_result = run_generator(
+            "--project-name",
+            "gitlink-service",
+            "--base-package",
+            "com.yss.gitlink",
+            "--output-dir",
+            str(gitlink_backend),
+            "--force",
+            "--contract-id",
+            "backend-scaffold-gitlink",
+            "--contract-version",
+            "1",
+            "--approval-ref",
+            "lifecycle/approval-gitlink",
+            "--router-draft-ref",
+            "router/draft-gitlink",
+            "--persisted-ref",
+            "lifecycle/contracts/backend-scaffold-gitlink.yaml",
+            "--contract-file",
+            str(gitlink_contract),
+            "--overwrite-scope",
+            "gitlink-service/**",
+            "--rollback-ref",
+            "git:checkpoint-gitlink",
+        )
+        require(
+            gitlink_result.returncode != 0
+            and "gitlink 不得由脚手架覆盖" in (gitlink_result.stdout + gitlink_result.stderr)
+            and "请显式传入 --force" not in (gitlink_result.stdout + gitlink_result.stderr),
+            "空 gitlink 挂载点不得被脚手架覆盖",
+        )
+        require(not (gitlink_project / "pom.xml").exists(), "拒绝 gitlink 覆盖时不得留下骨架")
+
     print("YSS 脚手架生成器受控生成场景验证通过")
     return 0
 

package/template/scripts/verify-skill-governance

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { validateSkillGovernance } from "./lib/skill-governance.mjs";
+
+try {
+  const result = validateSkillGovernance();
+  process.stdout.write(`技能规范冲突扫描通过（${result.legacy_aliases} 个兼容 alias）\n`);
+} catch (error) {
+  process.stderr.write(`技能规范冲突扫描失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/verify-template

@@ -5,7 +5,7 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT_DIR"
 node -e 'const [major]=process.versions.node.split(".").map(Number); if (major < 22 || major >= 27) { console.error("模板工具需要 Node >=22 <27"); process.exit(1); }'
 
-required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/agents/yss-skill-registry.yaml docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json docs/process/maintenance-intensity.yaml docs/process/schemas/lifecycle-checkpoint.schema.json docs/process/schemas/frontend-implementation-evidence.schema.json docs/process/templates/lifecycle-checkpoint-template.yaml docs/process/templates/frontend-implementation-plan-template.yaml docs/process/templates/frontend-implementation-verification-template.yaml scripts/repository-mode scripts/implementation-path-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/export-yss-skills)
+required_files=(yss-project.yaml AGENTS.md CONTEXT.md skills-lock.json docs/agents/yss-skill-registry.yaml docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json docs/process/maintenance-intensity.yaml docs/process/schemas/lifecycle-checkpoint.schema.json docs/process/schemas/frontend-implementation-evidence.schema.json docs/process/templates/lifecycle-checkpoint-template.yaml docs/process/templates/frontend-implementation-plan-template.yaml docs/process/templates/frontend-implementation-verification-template.yaml scripts/repository-mode scripts/implementation-path-policy scripts/repository-scope-policy scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-skill-governance scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/export-yss-skills)
 for required in "${required_files[@]}"; do test -f "$required" || { echo "缺少模板必需文件: $required" >&2; exit 1; }; done
 
 repository_mode="$(scripts/repository-mode)"
@@ -19,6 +19,7 @@ fi
 scripts/sync-skills --check
 scripts/update-skill-lock --check
 scripts/verify-skill-registry
+scripts/verify-skill-governance
 scripts/verify-yss-dto-openapi-profile
 scripts/verify-yss-dto-openapi-scenarios
 scripts/verify-lifecycle-registry
@@ -29,6 +30,7 @@ scripts/verify-lifecycle-scenarios
 scripts/verify-maintenance-intensity-scenarios
 scripts/verify-governance-release
 scripts/verify-implementation-path-scenarios
+scripts/verify-repository-scope-scenarios
 scripts/verify-scaffold-generator-scenarios
 scripts/verify-prototype-backend-scaffold-scenarios
 scripts/verify-matt-yss-integration-scenarios
@@ -37,7 +39,7 @@ scripts/verify-yss-ui-scenarios
 scripts/verify-openapi-yaml-first-scenarios
 scripts/verify-openapi-json-handoff-scenarios
 
-for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/export-yss-skills; do node --check "$entry"; done
+for entry in scripts/sync-skills scripts/update-skill-lock scripts/generate-lifecycle-artifacts scripts/verify-lifecycle-registry scripts/verify-lifecycle-checkpoint scripts/verify-frontend-implementation-evidence scripts/verify-maintenance-checkpoint scripts/verify-maintenance-intensity-scenarios scripts/verify-skill-registry scripts/verify-skill-governance scripts/verify-yss-dto-openapi-profile scripts/verify-yss-dto-openapi-scenarios scripts/verify-lifecycle-scenarios scripts/verify-matt-yss-integration-scenarios scripts/verify-prototype-backend-scaffold-scenarios scripts/verify-yss-router-scenarios scripts/verify-openapi-yaml-first-scenarios scripts/verify-openapi-json-handoff-scenarios scripts/verify-repository-scope-scenarios scripts/export-yss-skills; do node --check "$entry"; done
 
 legacy_runtime="ru""by"
 script_roots=(scripts)