create-yss-spec 2.1.15 → 2.2.1

package/template/scripts/lib/git-submodule-fixtures.mjs

@@ -0,0 +1,58 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+
+function git(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8" });
+}
+
+function initRepo(dir) {
+  mkdirSync(dir, { recursive: true });
+  git(dir, ["init", "-b", "main"]);
+  git(dir, ["config", "user.email", "test@example.invalid"]);
+  git(dir, ["config", "user.name", "fixture"]);
+  git(dir, ["config", "commit.gpgsign", "false"]);
+}
+
+export function makeGitlinkFixture({ checkout = "empty-gitlink" } = {}) {
+  const root = mkdtempSync(path.join(tmpdir(), "yss-gitlink-"));
+  const child = path.join(root, "child.git");
+  const superproject = path.join(root, "super");
+  initRepo(child);
+  writeFileSync(path.join(child, "README.md"), "child\n");
+  git(child, ["add", "."]);
+  git(child, ["commit", "-m", "init child"]);
+  const sha = git(child, ["rev-parse", "HEAD"]).trim();
+  initRepo(superproject);
+  mkdirSync(path.join(superproject, "apps/backend"), { recursive: true });
+  const mount = "apps/backend/billing-service";
+  if (checkout === "empty-gitlink") {
+    mkdirSync(path.join(superproject, mount), { recursive: true });
+    writeFileSync(
+      path.join(superproject, ".gitmodules"),
+      `[submodule "backend-billing-service"]\n\tpath = ${mount}\n\turl = ${child}\n`
+    );
+    git(superproject, ["update-index", "--add", "--cacheinfo", "160000", sha, mount]);
+    git(superproject, ["add", ".gitmodules"]);
+    git(superproject, ["commit", "-m", "empty gitlink"]);
+  } else {
+    git(superproject, ["-c", "protocol.file.allow=always", "submodule", "add", child, mount]);
+    git(superproject, ["commit", "-m", "add submodule"]);
+    if (checkout === "detached-head") {
+      git(path.join(superproject, mount), ["checkout", "--detach"]);
+    } else if (checkout === "attached-branch") {
+      git(path.join(superproject, mount), ["checkout", "-B", "main"]);
+    }
+  }
+  return {
+    root,
+    superproject,
+    child,
+    mount,
+    sha,
+    cleanup() {
+      rmSync(root, { recursive: true, force: true });
+    }
+  };
+}

package/template/scripts/lib/repository-scope-policy.mjs

@@ -0,0 +1,456 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { validImplementationPath, violation as pathViolation } from "./implementation-path-policy.mjs";
+
+export const REPOSITORY_SCOPES = Object.freeze([
+  "external-repository",
+  "harness-apps",
+  "git-submodule"
+]);
+
+export const LAYOUT_POLICIES = Object.freeze({
+  "external-repository": "external-repository-native",
+  "harness-apps": "harness-apps-multi-project",
+  "git-submodule": "git-submodule-harness-apps"
+});
+
+export const GITLINK_MODE = "160000";
+export const CHECKOUT_STATES = Object.freeze([
+  "attached-branch",
+  "detached-head",
+  "uninitialized",
+  "empty-gitlink"
+]);
+
+export const NAMED_STRESS_SCENARIOS = Object.freeze([
+  "unknown_scope",
+  "layout_mismatch",
+  "same_origin_url",
+  "copy_source_into_harness",
+  "missing_git_entry_mode",
+  "declared_harness_apps_actual_gitlink",
+  "empty_gitlink_as_regular_dir",
+  "detached_head_as_regular_dir",
+  "force_overlay_mount"
+]);
+
+function asString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeSlash(value) {
+  const text = asString(value);
+  if (!text) return "";
+  return text.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+
+function isDeclared(value) {
+  const text = asString(value);
+  return text !== "" && text !== "不适用";
+}
+
+function uniqueResolved(items) {
+  const seen = new Set();
+  const out = [];
+  for (const item of items) {
+    if (!item) continue;
+    const resolved = path.resolve(item);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    out.push(resolved);
+  }
+  return out;
+}
+
+export function expectedLayoutPolicy(scope) {
+  return LAYOUT_POLICIES[scope] ?? null;
+}
+
+export function violationRepositoryScope(record = {}) {
+  const scope = asString(record.repository_scope);
+  if (!REPOSITORY_SCOPES.includes(scope)) {
+    return `repository_scope must be one of ${REPOSITORY_SCOPES.join(" / ")}`;
+  }
+  const layout = asString(record.layout_policy);
+  const expected = expectedLayoutPolicy(scope);
+  if (layout && layout !== expected) {
+    return `layout_policy for ${scope} must be ${expected}`;
+  }
+  if (scope === "git-submodule") return gitSubmoduleRecordViolation(record);
+  if (scope === "harness-apps") return harnessAppsRecordViolation(record);
+  return externalRepositoryRecordViolation(record);
+}
+
+function gitSubmoduleRecordViolation(record) {
+  const projectRoot = normalizeSlash(record.project_root);
+  if (!projectRoot || !validImplementationPath(`${projectRoot}/`)) {
+    return `git-submodule project_root must be a concrete apps/backend/<project>/ or apps/frontend/<project>/ path: ${pathViolation(record.project_root || "") ?? "missing"}`;
+  }
+  if (!isDeclared(record.gitlink_path)) {
+    return "git-submodule gitlink_path is required";
+  }
+  const gitlinkPath = normalizeSlash(record.gitlink_path);
+  if (gitlinkPath !== projectRoot) {
+    return "git-submodule gitlink_path must equal project_root";
+  }
+  if (asString(record.git_entry_mode) !== GITLINK_MODE) {
+    return `git-submodule git_entry_mode must be ${GITLINK_MODE}`;
+  }
+  if (!asString(record.git_url)) return "git-submodule git_url is required";
+  if (!asString(record.gitmodules_name)) return "git-submodule gitmodules_name is required";
+  if (!asString(record.superproject_git_url)) {
+    return "git-submodule superproject_git_url is required";
+  }
+  if (asString(record.superproject_git_url) === asString(record.git_url)) {
+    return "git-submodule git_url must differ from superproject_git_url";
+  }
+  if (asString(record.layout_policy) && asString(record.layout_policy) !== LAYOUT_POLICIES["git-submodule"]) {
+    return `git-submodule layout_policy must be ${LAYOUT_POLICIES["git-submodule"]}`;
+  }
+  const checkout = asString(record.checkout_state);
+  if (!checkout) return "git-submodule checkout_state is required";
+  if (!CHECKOUT_STATES.includes(checkout)) {
+    return `git-submodule checkout_state must be one of ${CHECKOUT_STATES.join(" / ")}`;
+  }
+  if (checkout === "detached-head" && record.commit_allowed === true) {
+    return "git-submodule must not commit on detached HEAD";
+  }
+  if (checkout === "detached-head" && record.scaffold_status === "required") {
+    return "detached HEAD must not be treated as a regular directory";
+  }
+  if ((checkout === "uninitialized" || checkout === "empty-gitlink") && record.scaffold_status === "required") {
+    return "empty or uninitialized gitlink must not run scaffold_status=required";
+  }
+  if (record.force === true) {
+    return "--force must not overlay a git-submodule mount as a regular directory";
+  }
+  if (record.copy_source_into_harness === true) {
+    return "git-submodule must use gitlink mount, not copy implementation sources into the superproject";
+  }
+  return null;
+}
+
+function foreignGitlinkIdentityViolation(record, scope) {
+  if (asString(record.git_entry_mode) === GITLINK_MODE) {
+    return `${scope} cannot record a gitlink; use repository_scope: git-submodule`;
+  }
+  if (isDeclared(record.gitlink_path) || isDeclared(record.gitmodules_name) || isDeclared(record.superproject_git_url)) {
+    return `${scope} must not record git-submodule identity fields; use repository_scope: git-submodule`;
+  }
+  const checkout = asString(record.checkout_state);
+  if (isDeclared(checkout) && CHECKOUT_STATES.includes(checkout)) {
+    return `${scope} must not record git-submodule checkout_state; use repository_scope: git-submodule`;
+  }
+  return null;
+}
+
+function harnessAppsRecordViolation(record) {
+  const foreign = foreignGitlinkIdentityViolation(record, "harness-apps");
+  if (foreign) return foreign;
+  const projectRoot = normalizeSlash(record.project_root);
+  if (projectRoot && !validImplementationPath(`${projectRoot}/`)) {
+    return `harness-apps project_root must be a concrete apps/<kind>/<project>/ path: ${pathViolation(record.project_root)}`;
+  }
+  return null;
+}
+
+function externalRepositoryRecordViolation(record) {
+  const gitlinkPath = normalizeSlash(record.gitlink_path);
+  if (gitlinkPath && gitlinkPath.startsWith("apps/") && String(record.git_entry_mode) === GITLINK_MODE) {
+    return "external-repository cannot mount a gitlink under apps/; use repository_scope: git-submodule";
+  }
+  const foreign = foreignGitlinkIdentityViolation(record, "external-repository");
+  if (foreign) return foreign;
+  return null;
+}
+
+export function validRepositoryScope(record) {
+  return violationRepositoryScope(record) === null;
+}
+
+export 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 = normalizeSlash(pathMatch[1]);
+    const urlMatch = line.match(/^url\s*=\s*(.+)$/);
+    if (urlMatch) current.url = urlMatch[1].trim();
+  }
+  return modules;
+}
+
+export function readGitmodules(repoRoot) {
+  const file = path.join(repoRoot, ".gitmodules");
+  if (!existsSync(file)) return [];
+  return parseGitmodules(readFileSync(file, "utf8"));
+}
+
+export 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] };
+}
+
+export function findGitRoot(start) {
+  const roots = collectGitRoots(start);
+  return roots[0] ?? null;
+}
+
+export function collectGitRoots(start) {
+  if (!start) return [];
+  const roots = [];
+  let current = path.resolve(start);
+  while (true) {
+    if (existsSync(path.join(current, ".git")) || existsSync(path.join(current, ".gitmodules"))) {
+      roots.push(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return roots;
+}
+
+function isUnsafeCheckout(state) {
+  return state === "empty-gitlink" || state === "uninitialized" || state === "detached-head";
+}
+
+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 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 isEmptyDir(dir) {
+  if (!existsSync(dir)) return true;
+  try {
+    return readdirSync(dir).filter((name) => name !== "." && name !== "..").length === 0;
+  } catch {
+    return false;
+  }
+}
+
+export function isGitSubmoduleMount(repoRoot, targetPath) {
+  const relative = normalizeSlash(path.relative(repoRoot, path.resolve(targetPath)));
+  if (!relative || relative.startsWith("..")) return false;
+  const listed = readGitmodules(repoRoot).some((item) => item.path === relative);
+  if (listed) return true;
+  const staged = gitLsFilesStage(repoRoot, relative);
+  return staged?.mode === GITLINK_MODE;
+}
+
+export function isGitSubmoduleMountAnywhere(startOrRoot, targetPath) {
+  const roots = uniqueResolved([startOrRoot, ...collectGitRoots(targetPath), ...collectGitRoots(startOrRoot)]);
+  return roots.some((root) => isGitSubmoduleMount(root, targetPath));
+}
+
+export function inspectCheckoutState(repoRoot, targetPath) {
+  const resolved = path.resolve(targetPath);
+  const relative = repoRoot ? normalizeSlash(path.relative(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 = existsSync(path.join(resolved, ".git")) ? gitShowSuperproject(resolved) : "";
+  const isMount = staged?.mode === GITLINK_MODE || listed || Boolean(superproject);
+  const hasGit = 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;
+}
+
+export function actualWorkingTreeScope(repoRoot, targetPath) {
+  if (isGitSubmoduleMountAnywhere(repoRoot, targetPath) || gitShowSuperproject(targetPath)) {
+    return "git-submodule";
+  }
+  return "regular";
+}
+
+export function regularDirectoryMisreadViolation(record = {}, options = {}) {
+  const force = options.force === true;
+  const checkout = asString(record.checkout_state);
+  if (checkout === "empty-gitlink" || checkout === "uninitialized") {
+    return "empty gitlink must not be treated as a regular directory";
+  }
+  if (checkout === "detached-head") {
+    return "detached HEAD must not be treated as a regular directory";
+  }
+  if (options.repoRoot && options.targetPath) {
+    const inspected = inspectCheckoutState(options.repoRoot, options.targetPath);
+    if (inspected === "empty-gitlink" || inspected === "uninitialized") {
+      return "empty gitlink must not be treated as a regular directory";
+    }
+    if (inspected === "detached-head") {
+      return "detached HEAD must not be treated as a regular directory";
+    }
+    if (isGitSubmoduleMountAnywhere(options.repoRoot, options.targetPath) && force) {
+      return "--force must not overlay a git-submodule mount as a regular directory";
+    }
+  }
+  if (force && asString(record.repository_scope) === "git-submodule") {
+    return "--force must not overlay a git-submodule mount as a regular directory";
+  }
+  return null;
+}
+
+export function findEnclosingSubmoduleWorktree(repoRoot, start) {
+  let current = path.resolve(start);
+  const stop = repoRoot ? path.resolve(repoRoot) : null;
+  while (true) {
+    const roots = uniqueResolved([repoRoot, ...collectGitRoots(current)]);
+    for (const root of roots) {
+      if (path.resolve(root) === current) continue;
+      if (isGitSubmoduleMount(root, current)) {
+        return {
+          worktree: current,
+          superproject: root,
+          checkout: inspectCheckoutState(root, current)
+        };
+      }
+    }
+    if (existsSync(path.join(current, ".git"))) {
+      const superproject = gitShowSuperproject(current);
+      if (superproject) {
+        const checkout = inspectCheckoutState(superproject, current)
+          || (gitAbbrevRef(current) === "HEAD" ? "detached-head" : "attached-branch");
+        return { worktree: current, superproject, checkout };
+      }
+    }
+    if (stop && current === stop) break;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+export function overlayMountViolation(repoRoot, targetPath, { force = false } = {}) {
+  if (!isGitSubmoduleMountAnywhere(repoRoot, targetPath)) return null;
+  return force
+    ? "--force 不得把 git-submodule 挂载点当成普通目录覆盖；gitlink 不得由脚手架覆盖"
+    : "git-submodule gitlink 不得由脚手架覆盖；先 git submodule update --init，在子仓附加分支的工作树内生成，或改用 external-repository / harness-apps";
+}
+
+export function unsafeSubmoduleWorktreeViolation(repoRoot, targetPath) {
+  const enclosing = findEnclosingSubmoduleWorktree(repoRoot, targetPath);
+  if (!enclosing) return null;
+  if (enclosing.checkout === "empty-gitlink" || enclosing.checkout === "uninitialized") {
+    return "空 gitlink 不得当成普通目录写入；gitlink 不得由脚手架覆盖";
+  }
+  if (enclosing.checkout === "detached-head") {
+    return "detached HEAD 不得当成普通目录写入；gitlink 不得由脚手架覆盖";
+  }
+  return null;
+}
+
+export function implementationWriteViolation(repoRoot, targetPath, { force = false } = {}) {
+  return overlayMountViolation(repoRoot, targetPath, { force })
+    || unsafeSubmoduleWorktreeViolation(repoRoot, targetPath);
+}
+
+function freezeWorkingTreeInspection({ writable, violation, declared, actual }) {
+  return Object.freeze({
+    writable: writable === true,
+    violation: violation || null,
+    declared: Object.freeze(declared),
+    actual: Object.freeze(actual)
+  });
+}
+
+export function isWorkingTreeWritable(inspection) {
+  return inspection?.writable === true;
+}
+
+export function inspectWorkingTreeScope(repoRoot, record = {}) {
+  const projectRoot = normalizeSlash(record.project_root);
+  const declaredScope = asString(record.repository_scope);
+  const declaredCheckout = asString(record.checkout_state);
+  const declared = { scope: declaredScope, checkout: declaredCheckout };
+  if (!repoRoot || !projectRoot) {
+    return freezeWorkingTreeInspection({
+      writable: false,
+      violation: "working-tree inspection requires repoRoot and project_root",
+      declared,
+      actual: { scope: null, checkout: null }
+    });
+  }
+  const target = path.resolve(repoRoot, projectRoot);
+  const actualScope = actualWorkingTreeScope(repoRoot, target);
+  const actualCheckout = inspectCheckoutState(repoRoot, target);
+  const actual = { scope: actualScope, checkout: actualCheckout };
+  let violation = null;
+  if (declaredScope === "harness-apps" && actualScope === "git-submodule") {
+    violation = "工作树存在 gitlink / .gitmodules，不得登记为 harness-apps";
+  } else if (declaredScope === "external-repository" && actualScope === "git-submodule" && projectRoot.startsWith("apps/")) {
+    violation = "工作树存在 apps/ gitlink，不得登记为 external-repository";
+  } else if (declaredScope === "git-submodule" && actualScope !== "git-submodule") {
+    violation = "工作树不是 gitlink，不得登记为 git-submodule";
+  }
+  if (isUnsafeCheckout(declaredCheckout) || isUnsafeCheckout(actualCheckout)) {
+    const misread = regularDirectoryMisreadViolation({
+      checkout_state: isUnsafeCheckout(actualCheckout) ? actualCheckout : declaredCheckout
+    });
+    violation = violation ? `${violation}；${misread}` : misread;
+  } else if (!violation) {
+    violation = unsafeSubmoduleWorktreeViolation(repoRoot, target);
+  }
+  const writable = violation === null
+    && declaredCheckout !== "empty-gitlink"
+    && (declaredScope !== "git-submodule"
+      || (declaredCheckout === "attached-branch" && actualCheckout === "attached-branch"));
+  return freezeWorkingTreeInspection({ writable, violation, declared, actual });
+}
+
+export function gitSubmoduleScaffoldViolation(repositoryRoot, outputDir, projectName, { force = false } = {}) {
+  const resolvedOutput = path.resolve(outputDir);
+  const projectRoot = path.resolve(resolvedOutput, projectName);
+  const gitRoot = findGitRoot(projectRoot) || findGitRoot(resolvedOutput) || repositoryRoot || null;
+  return overlayMountViolation(gitRoot, projectRoot, { force })
+    || unsafeSubmoduleWorktreeViolation(gitRoot, projectRoot)
+    || unsafeSubmoduleWorktreeViolation(gitRoot, resolvedOutput)
+    || regularDirectoryMisreadViolation({}, { force, repoRoot: gitRoot, targetPath: projectRoot });
+}
+
+export function gitSubmoduleCommitViolation({ checkout_state, commit_authorized } = {}) {
+  if (checkout_state === "detached-head") {
+    return "git-submodule must checkout an attached branch before commit";
+  }
+  if (commit_authorized !== true) return "commit_authorized must be true";
+  return null;
+}
+
+export function gitSubmodulePushOrderViolation(order) {
+  const expected = ["submodule-repositories", "superproject-gitlink"];
+  if (!Array.isArray(order) || order.length !== expected.length || expected.some((item, index) => order[index] !== item)) {
+    return "git-submodule push/commit order must be submodule-repositories then superproject-gitlink";
+  }
+  return null;
+}

package/template/scripts/lib/scenario-checks.mjs

@@ -28,6 +28,9 @@ function validateMattContract(data) {
     ensure(git?.natural_language_intent_is_authorization === false && rule?.requires_explicit_user_authorization === true && rule?.authorized_value === true && rule?.unauthorized_action === "checkpoint-only", `${action} 授权边界不完整`);
     ensure(includesAll(rule?.required, [`${prefix}_authorized`, `${prefix}_scope`, `${prefix}_authorization_ref`]) && includesAll(rule?.non_empty, [`${prefix}_scope`, `${prefix}_authorization_ref`]), `${action} 授权必填字段不完整`);
   }
+  const submodule = git?.git_submodule;
+  ensure(submodule?.applies_when === "repository_scope=git-submodule" && submodule?.forbid_commit_on_detached_head === true && submodule?.empty_gitlink_scaffold === "blocked" && submodule?.treat_empty_gitlink_as_regular_dir === "blocked" && submodule?.treat_detached_head_as_regular_dir === "blocked" && submodule?.force_overlay_mount === "blocked" && submodule?.write_inside_detached_head === "blocked" && submodule?.require_git_entry_mode === "160000" && submodule?.working_tree_declared_scope_must_match === true && submodule?.copy_source_into_harness === "forbidden" && submodule?.clone_requires_recurse_submodules === true && submodule?.push_recurse_submodules === "check" && submodule?.delivery_order_must_include === "superproject-gitlink-update" && submodule?.nested_authorization === "per-repository" && submodule?.inspect_working_tree_writable === "explicit-boolean" && submodule?.empty_gitlink_writable === false && submodule?.force_overlay_regular_dir_path === "blocked", "git-submodule Git 授权契约不完整");
+  ensure(JSON.stringify(submodule?.commit_order) === JSON.stringify(["submodule-repositories", "superproject-gitlink"]) && JSON.stringify(submodule?.push_order) === JSON.stringify(["submodule-repositories", "superproject-gitlink"]), "git-submodule 先子后父顺序不完整");
 }
 
 function validateInvocationBoundary(data) {
@@ -54,6 +57,11 @@ function validateInvocationBoundary(data) {
   ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
   ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "research", "机会调研事实路由不准确");
   ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui"), "原生实现工作单元缺少 TDD 或 UI 路由");
+  const frontendRoute = routes?.["work-unit.slice-implementation"]?.frontend_route;
+  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口或页面编排技能");
+  for (const impact of ["api_impact", "formily_impact", "table_impact", "tree_impact", "height_impact", "export_impact", "theme_impact"]) {
+    ensure(Array.isArray(frontendRoute?.conditional_skills?.[impact]) && frontendRoute.conditional_skills[impact].length > 0 && typeof frontendRoute.not_applicable_reasons?.[impact] === "string", `前端条件专项路由缺少 ${impact}`);
+  }
   ensure(routes?.["work-unit.frontend-implementation-verification"]?.skills?.includes("code-review") && routes?.["work-unit.frontend-implementation-verification"]?.applies_when === "ui_impact", "前端还原验证未绑定 UI fidelity 审查轴");
   for (const id of ["work-unit.spec-synthesis", "work-unit.ticket-decomposition", "work-unit.slice-implementation"]) {
     ensure(routes?.[id]?.native?.source === "yss-product-lifecycle" && routes[id].compatibility?.source === "mattpocock/skills" && routes[id].compatibility.formal_artifact_owner === "explicit-user-entry", `${id} 未分离原生执行定义与 Matt 兼容输入`);
@@ -67,6 +75,12 @@ function validateInvocationBoundary(data) {
 function validateWorkflowExecutionResult(payload, contract, workUnitRoutes) {
   for (const field of contract.required) ensure(Object.hasOwn(payload, field), `Workflow Execution Result 缺少 ${field}`);
   ensure(contract.result_values.includes(payload.result), "Workflow Execution Result result 无效");
+  if (Object.hasOwn(payload, "unavailable_skill")) {
+    ensure(payload.result === contract.unavailable_skill.blocking_result, "技能不可用必须将 Workflow Execution Result 标记为 blocked");
+    for (const field of contract.unavailable_skill.required) {
+      ensure(typeof payload.unavailable_skill?.[field] === "string" && payload.unavailable_skill[field].trim(), `unavailable_skill.${field} 无效`);
+    }
+  }
   for (const field of contract.workflow_reference.required) ensure(typeof payload.workflow_reference?.[field] === "string" && payload.workflow_reference[field].trim(), `workflow_reference.${field} 无效`);
   const workUnit = workUnitRoutes?.[payload.work_unit];
   ensure(workUnit, `未知 Workflow Execution Result work_unit: ${payload.work_unit}`);
@@ -92,6 +106,7 @@ function validateMattProse(skill, adapter) {
   ensure(adapter.includes("仅发现旧路径资产") && adapter.includes("不得调用 `setup-matt-pocock-skills`"), "适配器缺少 setup 旧资产迁移或显式用户入口条件");
   ensure(adapter.includes("frontier 为空") && adapter.includes("双方共同理解已确认"), "适配器缺少 grill_exit 的 frontier 或共同理解条件");
   ensure(skill.includes("自然语言意向不构成上述结构化 Git 授权") && adapter.includes("本身不是结构化授权"), "主技能或适配器缺少自然语言 Git 意向不是授权的说明");
+  ensure(adapter.includes("禁止 detached HEAD 提交") && adapter.includes("先推子仓再更新父仓 gitlink"), "适配器缺少 git-submodule 嵌套 Git 授权说明");
 }
 
 function validateInvocationProse(skill, adapter, orchestration) {
@@ -185,6 +200,16 @@ export function runScenario(name) {
       blocking_signals: []
     };
     validateWorkflowExecutionResult(validResult, data.workflow_execution_result, data.work_unit_routes);
+    const unavailableResult = structuredClone(validResult);
+    unavailableResult.result = "blocked";
+    unavailableResult.unavailable_skill = { skill: "yss-ui", provider: "codex", fallback: "manual-review", resolution: "needs-human" };
+    unavailableResult.blocking_signals = ["missing_evidence"];
+    validateWorkflowExecutionResult(unavailableResult, data.workflow_execution_result, data.work_unit_routes);
+    const malformedUnavailable = structuredClone(unavailableResult);
+    delete malformedUnavailable.unavailable_skill.fallback;
+    let unavailableRejected = false;
+    try { validateWorkflowExecutionResult(malformedUnavailable, data.workflow_execution_result, data.work_unit_routes); } catch { unavailableRejected = true; }
+    ensure(unavailableRejected, "技能不可用结果缺少 fallback 时未被拒绝");
     const compatibleResult = structuredClone(validResult);
     compatibleResult.workflow_reference = { source: "mattpocock/skills", skill: "to-spec", invocation_mode: "reference" };
     validateWorkflowExecutionResult(compatibleResult, data.workflow_execution_result, data.work_unit_routes);
@@ -214,7 +239,13 @@ export function runScenario(name) {
       (item) => { item.matt_invocation_boundary.user_invoked_skills.push("unexpected-user-entry"); },
       (item) => { item.setup_readiness.lifecycle_may_invoke_setup = true; },
       (item) => { item.grill_exit.user_confirmation_required = false; },
-      (item) => { delete item.git_authorization.push; }
+      (item) => { delete item.git_authorization.push; },
+      (item) => { delete item.git_authorization.git_submodule; },
+      (item) => { item.git_authorization.git_submodule.forbid_commit_on_detached_head = false; },
+      (item) => { item.git_authorization.git_submodule.force_overlay_mount = "allowed"; },
+      (item) => { item.git_authorization.git_submodule.write_inside_detached_head = "allowed"; },
+      (item) => { item.git_authorization.git_submodule.empty_gitlink_writable = true },
+      (item) => { item.git_authorization.git_submodule.force_overlay_regular_dir_path = "allowed"; }
     ];
     for (const mutate of mutations) {
       const candidate = structuredClone(data); mutate(candidate);

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

@@ -0,0 +1,50 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadSkillRegistry } from "./skill-registry.mjs";
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+export function validateSkillGovernance({ read = (relative) => readFileSync(path.join(ROOT, relative), "utf8"), exists = (relative) => existsSync(path.join(ROOT, relative)) } = {}) {
+  const globalRules = read(".agents/rules/yss-ai-skills.md");
+  const tableSkill = read(".agents/skills/ytable-usage/SKILL.md");
+  const pageSkill = read(".agents/skills/yss-page-module-development/SKILL.md");
+
+  if (/toolbar-config\.custom.{0,30}(必须|必需)|必须.{0,30}toolbar-config\.custom/.test(globalRules)) {
+    fail("全局规则不得把 toolbar-config.custom 作为无条件要求");
+  }
+  for (const marker of ["主操作必须放入 `#toolbar-right`", "只有确实需要列设置时才使用", "toolbar-config"] ) {
+    if (!globalRules.includes(marker)) fail(`全局规则缺少条件化表格工具栏规则: ${marker}`);
+  }
+  for (const marker of ["无需配置 `:toolbar-config=\"{ custom: true }\"`", "仅在业务明确需要列设置时才传入"]) {
+    if (!tableSkill.includes(marker)) fail(`YTable 专项技能缺少条件化工具栏规则: ${marker}`);
+  }
+  if (!pageSkill.includes("只有确实需要列设置时才启用 `toolbar-config.custom`")) {
+    fail("页面模块 canonical 技能缺少条件化 toolbar-config 规则");
+  }
+
+  const registry = loadSkillRegistry();
+  const canonicalIds = new Set(registry.skills.map((skill) => skill.id));
+  const aliases = new Map(registry.skills.flatMap((skill) => skill.aliases.map((alias) => [alias, skill.id])));
+  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height", "yss-ui-business-page-generation"]);
+  for (const alias of legacy) {
+    if (exists(`.agents/skills/${alias}`)) fail(`legacy alias 不得存在独立 canonical 目录: ${alias}`);
+    if (!aliases.has(alias)) fail(`legacy alias 未登记: ${alias}`);
+  }
+  if (exists(".agents/skills/high-fidelity-html-prototype") || aliases.has("high-fidelity-html-prototype")) {
+    fail("high-fidelity-html-prototype 已退役，不得保留物理目录或运行时 alias");
+  }
+  for (const skill of registry.skills) {
+    if (!canonicalIds.has(skill.id)) fail(`注册表 canonical skill 无效: ${skill.id}`);
+    if (skill.maturity === "deprecated") {
+      for (const field of ["replaced_by", "migration_deadline", "cleanup_status"]) {
+        if (!skill[field] || typeof skill[field] !== "string") fail(`deprecated 技能缺少 ${field}: ${skill.id}`);
+      }
+    }
+  }
+  return { checked: true, legacy_aliases: legacy.size };
+}