create-yss-spec 3.0.0 → 3.0.1

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

@@ -8,8 +8,9 @@ export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
 const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
-export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
-export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
+const STRATEGIC_DESIGN_MANIFEST_PATH = path.join(SOURCE_ROOT, ".strategic-design-skills-manifest.json");
+export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
+export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "research", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web", "yss-router", "yss-source-index"]);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
   return names.filter((name) => obsolete.has(name)).sort();
 }
@@ -23,14 +24,16 @@ function treeFiles(directory, prefix = "") {
     const absolute = path.join(directory, entry.name);
     const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
     if (entry.isDirectory()) return treeFiles(absolute, rel);
-    if (rel.split("/").includes("__pycache__") || /\.(pyc|pyo)$/.test(rel)) return [];
+    if (rel.split("/").includes("__pycache__") || /\.(iml|pyc|pyo)$/.test(rel)) return [];
     return entry.isFile() || entry.isSymbolicLink() ? [[rel, absolute]] : [];
   });
 }
 export function treeHash(directory) {
   const digest = createHash("sha256");
   for (const [name, file] of treeFiles(directory).sort(([left], [right]) => left.localeCompare(right))) {
-    digest.update(name).update("\0").update(readFileSync(file)).update("\0");
+    const content = readFileSync(file);
+    const normalized = content.includes(0) ? content : Buffer.from(content.toString("utf8").replaceAll("\r\n", "\n"));
+    digest.update(name).update("\0").update(normalized).update("\0");
   }
   return digest.digest("hex");
 }
@@ -86,9 +89,33 @@ export function validateYssUiSkillManifest(manifest) {
   return manifest;
 }
 
+export function validateStrategicDesignSkillManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new TypeError("战略设计 skills 清单必须是对象");
+  for (const field of ["source", "source_type", "source_root", "source_revision", "adaptation_ref"]) {
+    if (typeof manifest[field] !== "string" || !manifest[field].trim()) throw new TypeError(`战略设计 skills 清单缺少 ${field}`);
+  }
+  if (manifest.schema_version !== 1) throw new TypeError("战略设计 skills 清单 schema_version 必须为 1");
+  if (!/^[0-9a-f]{40}$/.test(manifest.source_revision)) throw new TypeError("战略设计 skills source_revision 必须是完整 Git SHA");
+  if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) throw new TypeError("战略设计 skills 清单缺少 skills");
+  const upstreamNames = new Set();
+  const canonicalNames = new Set();
+  for (const skill of manifest.skills) {
+    if (!skill || typeof skill.upstream !== "string" || typeof skill.canonical !== "string") throw new TypeError("战略设计 skill 缺少 upstream/canonical");
+    if (!/^[0-9a-f]{64}$/.test(skill.upstream_hash ?? "")) throw new TypeError(`${skill.canonical} 缺少有效 upstream_hash`);
+    if (upstreamNames.has(skill.upstream)) throw new TypeError(`战略设计 upstream 重复: ${skill.upstream}`);
+    if (canonicalNames.has(skill.canonical)) throw new TypeError(`战略设计 canonical 重复: ${skill.canonical}`);
+    upstreamNames.add(skill.upstream);
+    canonicalNames.add(skill.canonical);
+  }
+  return manifest;
+}
+
 function loadYssUiSkillManifest() {
   return validateYssUiSkillManifest(JSON.parse(readFileSync(YSS_UI_MANIFEST_PATH, "utf8")));
 }
+function loadStrategicDesignSkillManifest() {
+  return validateStrategicDesignSkillManifest(JSON.parse(readFileSync(STRATEGIC_DESIGN_MANIFEST_PATH, "utf8")));
+}
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
 function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
@@ -179,7 +206,7 @@ function sourceRevisionMap(oldLock, arguments_) {
 function metadata(name, skillPath, directory, previous, canonical = false, sources = {}, upstreamRoot = null) {
   const old = previous[name] ?? {};
   let recordedPath = old.skillPath ?? skillPath;
-  if (canonical && /^\.(claude|codex|cursor|hermes|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
+  if (canonical && /^\.(claude|codex|cursor|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
   const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
   const sourceInfo = sources[result.source];
   if (sourceInfo?.revision) result.sourceRevision = sourceInfo.revision;
@@ -200,6 +227,9 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   const yssUiManifest = loadYssUiSkillManifest();
   sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
   const yssUiSkills = new Map(yssUiManifest.skills.map((skill) => [skill.canonical, skill]));
+  const strategicDesignManifest = loadStrategicDesignSkillManifest();
+  sources[strategicDesignManifest.source] = { ...(sources[strategicDesignManifest.source] ?? {}), revision: strategicDesignManifest.source_revision };
+  const strategicDesignSkills = new Map(strategicDesignManifest.skills.map((skill) => [skill.canonical, skill]));
   if (upstreamRoot && !existsSync(upstreamRoot)) throw new TypeError(`--upstream-root 不存在: ${upstreamRoot}`);
   const additions = arguments_.filter((arg) => arg.startsWith("--add=")).map((arg) => arg.slice(6));
   const removals = new Set(arguments_.filter((arg) => arg.startsWith("--remove=")).map((arg) => arg.slice(9)));
@@ -223,6 +253,16 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
       if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = yssUiManifest.adaptation_ref;
       else delete item.adaptationRef;
     }
+    const strategicDesignSkill = strategicDesignSkills.get(name);
+    if (strategicDesignSkill) {
+      item.source = strategicDesignManifest.source;
+      item.sourceType = strategicDesignManifest.source_type;
+      item.skillPath = `${strategicDesignManifest.source_root}/${strategicDesignSkill.upstream}/SKILL.md`;
+      item.sourceRevision = strategicDesignManifest.source_revision;
+      item.upstreamHash = strategicDesignSkill.upstream_hash;
+      if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = strategicDesignManifest.adaptation_ref;
+      else delete item.adaptationRef;
+    }
     item.targets = targets;
     return [name, item];
   }));

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

@@ -217,8 +217,8 @@ const markerFiles = [
   ["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-implementation-contract-compiler/references/slice-implementation-contract.md", "git-submodule-harness-apps"],
+  [".agents/skills/yss-implementation-contract-compiler/references/compiler-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"]

package/template/scripts/verify-retired-skill-ids

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { PROJECTION_ROOTS, ROOT } from "./lib/skill-supply-chain.mjs";
+
+const retired = ["yss-router", "yss-source-index"];
+const allowed = (relative) => relative === "docs/agents/skill-migrations.md"
+  || relative.includes("/docs/agents/skill-migrations.md")
+  || relative.endsWith(".template-source/wiki/raw/skill-migrations.md")
+  || relative.startsWith(".template-source/evidence/")
+  || relative.includes("/.template-source/evidence/")
+  || relative.includes("/tests/")
+  || relative.endsWith("scripts/verify-retired-skill-ids")
+  || relative.endsWith("scripts/lib/skill-supply-chain.mjs")
+  || relative.endsWith("scripts/lib/implementation-contract-compiler.mjs");
+
+const search = spawnSync("rg", ["-n", "--hidden", "--glob", "!.git/**", "--glob", "!.codegraph/**", "--glob", "!submodules/**", retired.join("|"), "."], {
+  cwd: ROOT,
+  encoding: "utf8"
+});
+if (![0, 1].includes(search.status)) {
+  process.stderr.write(search.stderr || "无法扫描退役 skill id\n");
+  process.exit(1);
+}
+const violations = search.stdout.split(/\r?\n/).filter(Boolean).filter((line) => {
+  const match = line.match(/^\.\/(.*?):\d+:/);
+  return !match || !allowed(match[1]);
+});
+for (const name of retired) {
+  const roots = [".agents/skills", ...PROJECTION_ROOTS];
+  for (const root of roots) if (existsSync(path.join(ROOT, root, name))) violations.push(`${root}/${name}: retired physical directory remains`);
+}
+if (violations.length) {
+  process.stderr.write(`退役 skill id 仍存在于活跃资产:\n${violations.join("\n")}\n`);
+  process.exitCode = 1;
+} else process.stdout.write("retired skill ids are absent from active assets\n");

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

@@ -60,7 +60,7 @@ def write_contract(
     project_name: str,
     contract_id: str,
     approval_ref: str,
-    router_draft_ref: str,
+    compiler_draft_ref: str,
     persisted_ref: str,
 ) -> None:
     contract = {
@@ -69,7 +69,7 @@ def write_contract(
         "contract_version": 1,
         "scaffold_request_id": f"{project_name}-request",
         "status": "approved",
-        "router_draft_ref": router_draft_ref,
+        "compiler_draft_ref": compiler_draft_ref,
         "lifecycle_approval_ref": approval_ref,
         "persisted_ref": persisted_ref,
         "current_version": 1,
@@ -154,7 +154,7 @@ def assert_pure_scaffold(project_root: Path, contract_id: str) -> None:
     require(manifest["contract_id"] == contract_id, "生成清单必须记录脚手架合同 ID")
     require(manifest["contract_version"] == 1, "生成清单必须记录脚手架合同版本")
     require(manifest["approval_ref"], "生成清单必须记录生命周期批准引用")
-    require(manifest["router_draft_ref"], "生成清单必须记录 Router draft 引用")
+    require(manifest["compiler_draft_ref"], "生成清单必须记录 实现合同编译器 draft 引用")
     require(manifest["persisted_ref"], "生成清单必须记录合同持久化引用")
     require(manifest["generation_mode"] == "controlled-generation", "生成清单必须记录受控生成模式")
     require(manifest["schema_version"] == 2, "生成清单必须使用 schema v2")
@@ -214,7 +214,7 @@ def main() -> int:
             "schemav1-service",
             "backend-scaffold-schema-v1",
             "lifecycle/approval-schema-v1",
-            "router/draft-schema-v1",
+            "compiler/draft-schema-v1",
             "lifecycle/contracts/backend-scaffold-schema-v1.yaml",
         )
         schema_v1_payload = json.loads(schema_v1_contract.read_text(encoding="utf-8"))
@@ -227,7 +227,7 @@ def main() -> int:
             "--contract-id", "backend-scaffold-schema-v1",
             "--contract-version", "1",
             "--approval-ref", "lifecycle/approval-schema-v1",
-            "--router-draft-ref", "router/draft-schema-v1",
+            "--compiler-draft-ref", "compiler/draft-schema-v1",
             "--persisted-ref", "lifecycle/contracts/backend-scaffold-schema-v1.yaml",
             "--contract-file", str(schema_v1_contract),
             "--group-id", "com.yss.datamiddle",
@@ -268,7 +268,7 @@ def main() -> int:
             "stale-service",
             "backend-scaffold-stale",
             "lifecycle/approval-stale",
-            "router/draft-stale",
+            "compiler/draft-stale",
             "lifecycle/contracts/backend-scaffold-stale.yaml",
         )
         stale_payload = json.loads(stale_contract.read_text(encoding="utf-8"))
@@ -287,8 +287,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-stale",
-            "--router-draft-ref",
-            "router/draft-stale",
+            "--compiler-draft-ref",
+            "compiler/draft-stale",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-stale.yaml",
             "--contract-file",
@@ -303,7 +303,7 @@ def main() -> int:
             "pure-service",
             "backend-scaffold-000",
             "lifecycle/approval-000",
-            "router/draft-000",
+            "compiler/draft-000",
             "lifecycle/contracts/backend-scaffold-000.yaml",
         )
 
@@ -320,8 +320,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-000",
-            "--router-draft-ref",
-            "router/draft-000",
+            "--compiler-draft-ref",
+            "compiler/draft-000",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-000.yaml",
             "--contract-file",
@@ -353,7 +353,7 @@ def main() -> int:
                     "contract_digest": "a" * 64,
                     "approval_ref": "lifecycle/verification",
                     "lifecycle_approval_ref": "lifecycle/verification",
-                    "router_draft_ref": "router/verification",
+                    "compiler_draft_ref": "router/verification",
                     "persisted_ref": "lifecycle/contracts/verification.yaml",
                     "contract_file_ref": "lifecycle/contracts/verification.json",
                     "current_version": 1,
@@ -501,7 +501,7 @@ def main() -> int:
         require(sentinel.read_text(encoding="utf-8") == "preserve me", "未批准覆盖不得改变原目录")
 
         force_contract = temp_root / "force-contract.json"
-        write_contract(force_contract, force_root, "force-service", "backend-scaffold-001", "lifecycle/approval-001", "router/draft-001", "lifecycle/contracts/backend-scaffold-001.yaml")
+        write_contract(force_contract, force_root, "force-service", "backend-scaffold-001", "lifecycle/approval-001", "compiler/draft-001", "lifecycle/contracts/backend-scaffold-001.yaml")
         approved_force_result = run_generator(
             "--project-name",
             "force-service",
@@ -516,8 +516,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-001",
-            "--router-draft-ref",
-            "router/draft-001",
+            "--compiler-draft-ref",
+            "compiler/draft-001",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-001.yaml",
             "--contract-file",
@@ -553,7 +553,7 @@ def main() -> int:
             "gitlink-service",
             "backend-scaffold-gitlink",
             "lifecycle/approval-gitlink",
-            "router/draft-gitlink",
+            "compiler/draft-gitlink",
             "lifecycle/contracts/backend-scaffold-gitlink.yaml",
         )
         gitlink_result = run_generator(
@@ -569,8 +569,8 @@ def main() -> int:
             "1",
             "--approval-ref",
             "lifecycle/approval-gitlink",
-            "--router-draft-ref",
-            "router/draft-gitlink",
+            "--compiler-draft-ref",
+            "compiler/draft-gitlink",
             "--persisted-ref",
             "lifecycle/contracts/backend-scaffold-gitlink.yaml",
             "--contract-file",

package/template/scripts/verify-template-verification-scenarios

@@ -36,7 +36,10 @@ const releaseBaseline = [
   "scripts/verify-scaffold-generator-scenarios",
   "scripts/verify-prototype-backend-scaffold-scenarios",
   "scripts/verify-matt-yss-integration-scenarios",
-  "scripts/verify-yss-router-scenarios",
+  "scripts/verify-yss-implementation-contract-compiler-scenarios",
+  "scripts/generate-yss-skill-boundaries --check",
+  "scripts/audit-yss-backend-skills --check",
+  "scripts/verify-retired-skill-ids",
   "scripts/verify-yss-ui-scenarios",
   "scripts/verify-yss-prototype-contract-scenarios",
   "node .agents/skills/yss-prototype-stage/scripts/prototype-contract.mjs validate-evidence docs/design/templates/prototype-evidence-template.yaml --allow-template",

package/template/scripts/verify-yss-implementation-contract-compiler-scenarios

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { runScenario } from "./lib/scenario-checks.mjs";
+
+try {
+  runScenario("implementationContractCompiler");
+  const result = spawnSync(process.execPath, ["--test", ".agents/skills/yss-implementation-contract-compiler/tests/compiler-scenarios.test.mjs"], { encoding: "utf8" });
+  process.stdout.write(result.stdout);
+  process.stderr.write(result.stderr);
+  if (result.status !== 0) process.exitCode = result.status ?? 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}