create-yss-spec 2.1.4 → 2.1.6

package/template/scripts/lib/export-skills.mjs

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const sourceRoot = path.join(root, ".agents/skills");
+const managed = ["skills", "skills.sh.json", ".yss-export-manifest.json"];
+const forbidden = ["AGENTS.md", "CONTEXT.md", "docs", "skills-lock.json", ".agents", ".claude", ".codex", ".hermes", ".pi", ".qoder", ".trae"];
+const hash = (content) => createHash("sha256").update(content).digest("hex");
+const fail = (message) => { throw new TypeError("export-yss-skills: " + message); };
+
+function files(directory, prefix = "") {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+    if (entry.name === ".DS_Store") return [];
+    const absolute = path.join(directory, entry.name);
+    const relative = prefix ? prefix + "/" + entry.name : entry.name;
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink()) fail("symbolic links are not allowed: " + absolute);
+    if (stat.isDirectory()) return files(absolute, relative);
+    if (stat.isFile()) return [[relative, absolute]];
+    fail("unsupported source entry: " + absolute);
+  });
+}
+
+function parseFrontmatter(bytes, source) {
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(bytes.toString("utf8"));
+  if (!match) fail("invalid frontmatter: " + source);
+  const fields = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const index = line.indexOf(":");
+    if (index < 0) continue;
+    const key = line.slice(0, index).trim();
+    let value = line.slice(index + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) value = value.slice(1, -1);
+    fields[key] = value;
+  }
+  for (const key of ["name", "description"]) if (typeof fields[key] !== "string" || !fields[key]) fail("frontmatter " + key + " must be a string: " + source);
+  return fields;
+}
+
+function sanitize(text, relative) {
+  if (relative.endsWith("assets/wrapper/.mvn/maven.config")) return "# Optional consuming-project Maven deployment configuration.\n# Configure repository URLs and profiles in the consuming project or CI.\n";
+  const directory = path.posix.dirname(relative);
+  const prefixPath = path.posix.relative("skills/" + (directory === "." ? "" : directory), "skills");
+  const prefix = prefixPath ? prefixPath + "/" : "";
+  let value = text.replace(/(YSS_SKILLS_ROOT\s*=\s*["']?)\/path\/to\/\.agents\/skills/g, "$1__YSS_SKILLS_ROOT_PATH__");
+  value = value.replace(/\/path\/to\/\.agents\/skills/g, "$YSS_SKILLS_ROOT");
+  value = value.replace(/(?:\$\{base_project\}\/)?(?:\/path\/to\/)?\.(?:agents|claude|codex|hermes|pi|qoder|trae)\/skills\//g, prefix);
+  value = value.replace(/\.(?:agents|claude|codex|hermes|pi|qoder|trae)\/skills\b/g, "the canonical public skill source");
+  value = value.replace(/\/path\/to\/skill-creator/g, "skill-creator").replace(/(?<![\w.])\/path\//g, "./path/");
+  value = value.replace(/\/(?:Users|home|private)\/[^\s"'()<>\]]+/g, "<local-path-removed>").replace(/\/tmp\//g, "./tmp/");
+  value = value.replace(/yss-spec-project-template/g, "the consuming project").replace(/\$\{base_project\}/g, "the consuming project");
+  value = value.replace(/\[([^\]]*)\]\(https?:\/\/192\.168\.[^\s)]+\)/g, "$1").replace(/https?:\/\/192\.168\.[^\s)]+/g, "the consuming project optional YSS documentation");
+  if (relative.includes("/assets/docs/guide/")) value = value.replace(/(\]\(\.\/)guide\//g, "$1");
+  if (relative.includes("/assets/docs/")) value = value.replace(/\[([^\]]+)\]\(\/(guide|components|hooks|utils)(\/[^)#]+)?(#[^)]*)?\)/g, (_all, label, section, suffix, fragment = "") => {
+    if (section === "utils") return label;
+    const route = suffix ? suffix.slice(1) : null;
+    const target = section === "guide" ? (route ? "./" + route + ".md" : "./") : section === "components" ? "../components/" + route + ".md" : (route ? "../hooks/" + route + ".md" : "../hooks/");
+    return "[" + label + "](" + target + fragment + ")";
+  });
+  value = value.replace(/((?:["']?(?:password|passwd|secret|token|api[_-]?key|access[_-]?key)["']?\s*[:=]\s*["']))[^"'\r\n]*(["'])/gi, "$1CHANGE_ME$2");
+  value = value.replace(/(["'])(?:admin123|guest|123456)\1/gi, "$1CHANGE_ME$1").replace(/__YSS_SKILLS_ROOT_PATH__/g, "./path/to/yss-skills");
+  if (relative.endsWith("SKILL.md") && !value.includes("消费项目上下文")) {
+    const header = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/.exec(value);
+    if (header) value = header[0] + "\n> **消费项目上下文：** 本公开技能包不携带消费项目的 AGENTS.md、CONTEXT.md 或 docs/。文档中出现的这些路径均指可选的消费项目上下文；技能自身所需的参考资料、资源和脚本已随技能一同提供。\n" + value.slice(header[0].length);
+  }
+  return value.split(/\r?\n/).map((line) => line.replace(/[ \t]+$/, "")).join("\n").replace(/\n*$/, "") + "\n";
+}
+
+function validateLinks(skillsRoot) {
+  for (const [relative, absolute] of files(skillsRoot)) {
+    if (!relative.endsWith(".md")) continue;
+    for (const found of readFileSync(absolute, "utf8").matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
+      let href = found[1].trim().split(/[ \t]+/, 1)[0];
+      if (href.startsWith("<") && href.endsWith(">")) href = href.slice(1, -1);
+      if (!href || /^(#|https?:\/\/|mailto:|<|\$\{)/.test(href)) continue;
+      const target = href.split("#", 1)[0];
+      if (!target) continue;
+      const resolved = path.resolve(path.dirname(absolute), target);
+      if (resolved !== skillsRoot && !resolved.startsWith(skillsRoot + path.sep)) fail("link escapes public export: " + relative + " -> " + href);
+      if (!existsSync(resolved)) fail("broken internal link: " + relative + " -> " + href);
+    }
+  }
+}
+
+function validate(output, skillNames) {
+  for (const name of skillNames) {
+    const source = path.join(output, "skills", name, "SKILL.md");
+    if (!existsSync(source) || !lstatSync(source).isFile()) fail("missing exported skill: " + source);
+  }
+  for (const entry of forbidden) if (existsSync(path.join(output, entry))) fail("forbidden project file in public export: " + entry);
+  for (const [_relative, absolute] of files(path.join(output, "skills"))) {
+    const bytes = readFileSync(absolute);
+    if (bytes.includes(0)) continue;
+    const text = bytes.toString("utf8");
+    if (/-----BEGIN (?:[A-Z0-9 ]+ )?PRIVATE KEY-----|(?:ghp_|github_pat_|github_token_|xox[baprs]-)[A-Za-z0-9_-]+|AKIA[0-9A-Z]{16}/.test(text)) fail("suspicious credential-like content: " + absolute);
+    if (/(?:^|[^.\w])\/(?:Users|home|private|tmp)\//.test(text)) fail("absolute local path in public export: " + absolute);
+    if (/\.(?:agents|claude|codex|hermes|pi|qoder|trae)\/skills/.test(text)) fail("Agent root path in public export: " + absolute);
+  }
+  validateLinks(path.join(output, "skills"));
+}
+
+function loadConfig() {
+  let data;
+  try { data = JSON.parse(readFileSync(path.join(root, "yss-public-skills.json"), "utf8")); } catch (error) { fail("invalid yss-public-skills.json: " + error.message); }
+  if (!Array.isArray(data.skills) || !data.skills.length || new Set(data.skills).size !== data.skills.length || data.skills.some((item) => !/^yss-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(item))) fail("yss-public-skills.json skills must be a unique non-empty skill-directory array");
+  if (data.canonical_root !== ".agents/skills") fail("canonical_root must be .agents/skills");
+  if (!Array.isArray(data.groupings) || !data.groupings.length) fail("yss-public-skills.json groupings must be a non-empty array");
+  const grouped = data.groupings.flatMap((group) => {
+    if (!group || typeof group.title !== "string" || !group.title || typeof group.description !== "string" || !Array.isArray(group.skills) || !group.skills.length || group.skills.some((skill) => !data.skills.includes(skill))) fail("invalid public skill grouping");
+    return group.skills;
+  });
+  if (new Set(grouped).size !== grouped.length || [...grouped].sort().join("\0") !== [...data.skills].sort().join("\0")) fail("public grouping must cover every listed skill exactly once");
+  return data;
+}
+
+function ensureOutput(output) {
+  if (!existsSync(sourceRoot) || lstatSync(sourceRoot).isSymbolicLink()) fail("canonical skill root is missing or a symbolic link");
+  const canonical = realpathSync(sourceRoot);
+  if (output === canonical || output.startsWith(canonical + path.sep) || canonical.startsWith(output + path.sep)) fail("output directory must not overlap canonical skills: " + output);
+  if (existsSync(output) && lstatSync(output).isSymbolicLink()) fail("output directory must not be a symbolic link: " + output);
+  if (existsSync(output)) {
+    for (const entry of managed) if (existsSync(path.join(output, entry)) && lstatSync(path.join(output, entry)).isSymbolicLink()) fail("managed export path must not be a symbolic link: " + path.join(output, entry));
+    for (const entry of forbidden) if (existsSync(path.join(output, entry))) fail("forbidden project file in public export: " + entry);
+  }
+}
+
+function build(output, data) {
+  ensureOutput(output); mkdirSync(output, { recursive: true });
+  for (const entry of managed) rmSync(path.join(output, entry), { recursive: true, force: true });
+  mkdirSync(path.join(output, "skills"), { recursive: true });
+  const exported = [];
+  for (const directory of data.skills) {
+    const source = path.join(sourceRoot, directory);
+    if (!existsSync(source) || lstatSync(source).isSymbolicLink() || !lstatSync(source).isDirectory()) fail("listed skill directory invalid: " + source);
+    const skillFile = path.join(source, "SKILL.md");
+    if (!existsSync(skillFile) || !lstatSync(skillFile).isFile()) fail("listed skill has no SKILL.md: " + skillFile);
+    const fields = parseFrontmatter(readFileSync(skillFile), skillFile);
+    const normalized = fields.name.toLowerCase().replace(/[\s_]+/g, "-");
+    if (exported.some((item) => item.name.toLowerCase().replace(/[\s_]+/g, "-") === normalized)) fail("duplicate normalized skill name: " + fields.name);
+    const destination = path.join(output, "skills", directory); mkdirSync(destination, { recursive: true });
+    const listed = [];
+    for (const [relative, absolute] of files(source)) {
+      const target = path.join(destination, relative); mkdirSync(path.dirname(target), { recursive: true });
+      const bytes = readFileSync(absolute); const decoded = bytes.toString("utf8");
+      writeFileSync(target, bytes.includes(0) || decoded.includes("\uFFFD") ? bytes : sanitize(decoded, directory + "/" + relative));
+      chmodSync(target, lstatSync(absolute).mode & 0o7777); listed.push(relative);
+    }
+    exported.push({ directory, name: fields.name, description: fields.description, files: listed.sort() });
+  }
+  const names = Object.fromEntries(exported.map((item) => [item.directory, item.name]));
+  writeFileSync(path.join(output, "skills.sh.json"), JSON.stringify({ "$schema": "https://skills.sh/schemas/skills.sh.schema.json", notGrouped: "bottom", groupings: data.groupings.map((group) => ({ ...group, skills: group.skills.map((directory) => names[directory]) })) }, null, 2) + "\n");
+  const generated = Object.fromEntries(files(path.join(output, "skills")).map(([relative, absolute]) => [relative, hash(readFileSync(absolute))]));
+  writeFileSync(path.join(output, ".yss-export-manifest.json"), JSON.stringify({ format_version: 1, source: { repository: data.repository, canonical_root: data.canonical_root }, skills: exported, generated_files_sha256: generated }, null, 2) + "\n");
+  validate(output, data.skills);
+}
+
+function fileMap(directory) {
+  const output = new Map();
+  for (const entry of managed) {
+    const target = path.join(directory, entry);
+    if (!existsSync(target)) { output.set(entry, null); continue; }
+    if (lstatSync(target).isDirectory()) for (const [relative, absolute] of files(target)) output.set(entry + "/" + relative, readFileSync(absolute));
+    else output.set(entry, readFileSync(target));
+  }
+  return output;
+}
+
+export function exportSkills(argv = process.argv.slice(2)) {
+  if (argv.includes("-h") || argv.includes("--help")) return "Usage: scripts/export-yss-skills --output DIR [--check]";
+  const position = argv.indexOf("--output");
+  if (position < 0 || !argv[position + 1]) fail("--output is required");
+  const output = path.resolve(argv[position + 1]); const data = loadConfig();
+  if (!argv.includes("--check")) { build(output, data); return "Exported " + data.skills.length + " YSS skills to " + output; }
+  ensureOutput(output); if (!existsSync(output) || !lstatSync(output).isDirectory()) fail("export directory does not exist: " + output);
+  const temporary = mkdtempSync(path.join(tmpdir(), "yss-export-check-"));
+  try {
+    build(temporary, data); validate(output, data.skills);
+    const expected = fileMap(temporary); const actual = fileMap(output);
+    if (expected.size !== actual.size || [...expected].some(([key, value]) => !actual.has(key) || !value.equals(actual.get(key)))) fail("export is out of date; managed file list or content differs");
+    return "YSS public export is up to date: " + output;
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+}

package/template/scripts/lib/implementation-path-policy.mjs

@@ -0,0 +1,32 @@
+const PROJECT_NAME = /^[a-z][a-z0-9-]*$/;
+const IMPLEMENTATION_KINDS = new Set(["backend", "frontend"]);
+
+export function normalizeImplementationPath(value) {
+  if (typeof value !== "string" || value.length === 0) return null;
+  const candidate = value.endsWith("/") ? value.slice(0, -1) : value;
+  if (candidate.length === 0 || candidate.startsWith("/") || candidate.startsWith("../")) return null;
+  const parts = candidate.split("/");
+  if (parts.some((part) => part === "" || part === "." || part === "..")) return null;
+  return candidate;
+}
+
+export function violation(value, { enforceHarness = true } = {}) {
+  const clean = normalizeImplementationPath(value);
+  if (!clean) return "implementation path must be a clean relative path";
+  if (!enforceHarness) return null;
+  const parts = clean.split("/");
+  const root = parts.slice(0, 2).join("/");
+  if (parts.length >= 2 && parts[0] === "app" && IMPLEMENTATION_KINDS.has(parts[1])) {
+    return `singular app implementation root is forbidden: ${root}/`;
+  }
+  if (!(parts[0] === "apps" && IMPLEMENTATION_KINDS.has(parts[1]))) return null;
+  if (parts.length < 3) return `implementation container root is not a project root: ${root}/`;
+  if (!PROJECT_NAME.test(parts[2])) {
+    return `implementation project segment must be a concrete project name: ${parts[2]}`;
+  }
+  return null;
+}
+
+export function validImplementationPath(value, options) {
+  return violation(value, options) === null;
+}

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

@@ -0,0 +1,175 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocument } from "../vendor/yaml.mjs";
+
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const DEFAULT_REGISTRY = path.join(ROOT, "docs/process/lifecycle-registry.yaml");
+export const DEFAULT_BASELINE = path.join(ROOT, "docs/process/lifecycle-registry-baseline.json");
+const ID_PATTERN = /^(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*$/;
+const COLLECTIONS = ["stages", "gates", "artifacts", "work_units", "evidence"];
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function yamlFromFile(filePath, label) {
+  let source;
+  try {
+    source = readFileSync(filePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") fail(`缺少${label}: ${filePath}`);
+    throw error;
+  }
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) fail(`无法解析${label}: ${document.errors[0].message}`);
+  let value;
+  try {
+    value = document.toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    fail(`无法解析${label}: ${error.message}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(`${label}必须是对象`);
+  return value;
+}
+
+export function loadRegistry(filePath = DEFAULT_REGISTRY) {
+  return yamlFromFile(filePath, "生命周期注册表");
+}
+
+function requireReference(ids, reference, field) {
+  if (!ids.has(reference)) fail(`${field} 引用了不存在的引用: ${reference}`);
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+  }
+  return value;
+}
+
+export function semanticProjection(registry) {
+  return COLLECTIONS.flatMap((kind) => registry[kind].map((record) => ({ kind, record: canonicalize(record) })))
+    .sort((left, right) => left.record.id.localeCompare(right.record.id));
+}
+
+export function semanticDigest(registry) {
+  return createHash("sha256").update(JSON.stringify(semanticProjection(registry))).digest("hex");
+}
+
+function validateBaseline(registry, ids, baselinePath) {
+  let baseline;
+  try {
+    baseline = JSON.parse(readFileSync(baselinePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") fail(`缺少生命周期已发布基线: ${path.relative(ROOT, baselinePath)}`);
+    if (error instanceof SyntaxError) fail(`无法解析生命周期已发布基线: ${error.message}`);
+    throw error;
+  }
+  if (baseline.schema_version !== 1 || baseline.registry_id !== registry.registry_id) {
+    fail("生命周期已发布基线版本或 registry_id 不匹配");
+  }
+  const publishedIds = baseline.published_ids;
+  if (!Array.isArray(publishedIds) || new Set(publishedIds).size !== publishedIds.length) {
+    fail("生命周期已发布基线缺少 published_ids");
+  }
+  for (const id of publishedIds) {
+    if (typeof id !== "string" || !ID_PATTERN.test(id)) fail(`生命周期已发布基线包含无效 ID: ${JSON.stringify(id)}`);
+  }
+  const activeIds = [...ids.keys()].sort();
+  const deprecated = registry.id_policy.deprecated_ids;
+  if (new Set(deprecated).size !== deprecated.length || deprecated.some((id) => !publishedIds.includes(id)) || deprecated.some((id) => activeIds.includes(id))) {
+    fail("deprecated_ids 必须唯一、来自已发布 ID，且不得仍为活跃对象");
+  }
+  const expected = publishedIds.filter((id) => !deprecated.includes(id)).sort();
+  if (JSON.stringify(activeIds) !== JSON.stringify(expected)) {
+    fail("生命周期活跃 ID 与已发布基线不一致；新增、移除或弃用必须先更新发布基线");
+  }
+  if (baseline.semantic_sha256 !== semanticDigest(registry)) fail("生命周期稳定 ID 的语义快照已变化；不得复用已发布 ID");
+}
+
+export function validateRegistry(registry, { baseline = DEFAULT_BASELINE } = {}) {
+  const required = ["schema_version", "registry_id", "status", "id_policy", ...COLLECTIONS];
+  const missing = required.filter((key) => !(key in registry));
+  if (missing.length > 0) fail(`生命周期注册表缺少字段: ${missing.join(", ")}`);
+  if (registry.schema_version !== 1) fail("仅支持 lifecycle registry schema_version: 1");
+  if (registry.registry_id !== "yss.lifecycle") fail("registry_id 必须为 yss.lifecycle");
+  if (!new Set(["shadow", "active"]).has(registry.status)) fail("status 必须为 shadow 或 active");
+  const policy = registry.id_policy;
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) fail("id_policy 必须是对象");
+  for (const key of ["pattern", "published_ids_immutable", "baseline", "deprecated_ids"]) {
+    if (!(key in policy)) fail(`id_policy 缺少字段: ${key}`);
+  }
+  if (policy.published_ids_immutable !== true) fail("published_ids_immutable 必须为 true");
+  if (policy.pattern !== "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$") fail("id_policy.pattern 不符合固定命名空间");
+  if (policy.baseline !== "docs/process/lifecycle-registry-baseline.json") fail("id_policy.baseline 必须指向发布基线");
+  if (!Array.isArray(policy.deprecated_ids)) fail("deprecated_ids 必须是数组");
+  const ids = new Map();
+  for (const collection of COLLECTIONS) {
+    const records = registry[collection];
+    if (!Array.isArray(records) || records.length === 0) fail(`${collection} 必须是非空数组`);
+    for (const record of records) {
+      const id = record?.id;
+      if (typeof id !== "string" || !ID_PATTERN.test(id)) fail(`${collection} 中存在无效 ID: ${JSON.stringify(id)}`);
+      if (ids.has(id)) fail(`生命周期 ID 重复: ${id}`);
+      const prefix = collection === "work_units" ? "work-unit." : collection === "evidence" ? "evidence." : `${collection.slice(0, -1)}.`;
+      if (!id.startsWith(prefix)) fail(`${id} 与 ${collection} 类型不匹配`);
+      if (typeof record.name !== "string" || record.name.length === 0) fail(`${id} 缺少名称`);
+      ids.set(id, collection);
+    }
+  }
+  for (const gate of registry.gates) {
+    requireReference(ids, gate.stage, `${gate.id}.stage`);
+    if (ids.get(gate.stage) !== "stages") fail(`${gate.id}.stage 必须引用 stage.*`);
+    if (!Array.isArray(gate.evidence) || gate.evidence.length === 0) fail(`${gate.id}.evidence 必须是非空数组`);
+    for (const reference of gate.evidence) {
+      requireReference(ids, reference, `${gate.id}.evidence`);
+      if (ids.get(reference) !== "evidence") fail(`${gate.id}.evidence 必须引用 evidence.*`);
+    }
+  }
+  for (const artifact of registry.artifacts) {
+    requireReference(ids, artifact.stage, `${artifact.id}.stage`);
+    if (ids.get(artifact.stage) !== "stages") fail(`${artifact.id}.stage 必须引用 stage.*`);
+  }
+  if (baseline) validateBaseline(registry, ids, baseline);
+  return registry;
+}
+
+export function renderLifecycleStructure(registry) {
+  const lines = [
+    "<!-- lifecycle-registry:structure:start -->",
+    `> 此结构区由 \`docs/process/lifecycle-registry.yaml\` 生成。当前为 \`${registry.status}\` 模式：它校验结构和派生文档，不改变运行时状态 schema 或人工批准语义。`, "",
+    "## 1. 主阶段", "", "| 稳定 ID | 阶段 | 目标 | 退出标准 |", "|---|---|---|---|"
+  ];
+  for (const stage of registry.stages) lines.push(`| \`${stage.id}\` | ${stage.name} | ${stage.goal} | ${stage.exit_criteria} |`);
+  lines.push("", "## 2. 生命周期对象", "", "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 \`not-applicable\` 及原因，不生成空文档。", "", "### 2.1 条件门禁", "", "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 必须留下的证据 |", "|---|---|---|---|---|");
+  for (const gate of registry.gates) lines.push(`| \`${gate.id}\` | ${gate.name} | \`${gate.stage}\` | ${gate.trigger} | ${gate.evidence.map((id) => `\`${id}\``).join("、")} |`);
+  lines.push("", "### 2.2 生命周期产物", "", "| 稳定 ID | 产物 | 所属阶段 | 触发条件 |", "|---|---|---|---|");
+  for (const artifact of registry.artifacts) lines.push(`| \`${artifact.id}\` | ${artifact.name} | \`${artifact.stage}\` | ${artifact.trigger} |`);
+  lines.push("", "### 2.3 执行证据", "", "| 稳定 ID | 证据 | 说明 |", "|---|---|---|");
+  for (const evidence of registry.evidence) lines.push(`| \`${evidence.id}\` | ${evidence.name} | ${evidence.description} |`);
+  lines.push("<!-- lifecycle-registry:structure:end -->");
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderWorkUnits(registry) {
+  const lines = ["<!-- lifecycle-registry:work-units:start -->", "> 此表由 `docs/process/lifecycle-registry.yaml` 生成；它只描述 `template-source` 的 Harness 工作单元。", "", "| 稳定 ID | 工作单元 | 输入 | 输出 | 完成条件 |", "|---|---|---|---|---|"];
+  for (const unit of registry.work_units) lines.push(`| \`${unit.id}\` | ${unit.name} | ${unit.input} | ${unit.output} | ${unit.completion} |`);
+  lines.push("<!-- lifecycle-registry:work-units:end -->");
+  return `${lines.join("\n")}\n`;
+}
+
+export function replaceRegion(filePath, startMarker, endMarker, replacement, { check = false } = {}) {
+  const body = readFileSync(filePath, "utf8");
+  const escaped = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const expression = new RegExp(`${escaped(startMarker)}[\\s\\S]*?${escaped(endMarker)}\\n?`);
+  if (!expression.test(body)) fail(`派生文档缺少生成区: ${path.relative(ROOT, filePath)}`);
+  const expected = body.replace(expression, replacement);
+  if (check) {
+    if (expected !== body) fail(`派生文档与注册表漂移: ${path.relative(ROOT, filePath)}；运行 scripts/generate-lifecycle-artifacts --write`);
+  } else {
+    writeFileSync(filePath, expected, "utf8");
+  }
+}

package/template/scripts/lib/repository-mode.mjs

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { parseDocument } from "../vendor/yaml.mjs";
+
+const VALID_MODES = new Set(["template-source", "project-instance"]);
+
+export function readRepositoryMode(root = process.cwd()) {
+  const manifestPath = path.join(root, "yss-project.yaml");
+  let source;
+  try {
+    source = readFileSync(manifestPath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new TypeError(`缺少 yss-project.yaml: ${error.message}`);
+    }
+    throw error;
+  }
+  const document = parseDocument(source, { maxAliasCount: 0, uniqueKeys: true });
+  if (document.errors.length > 0) {
+    throw new TypeError(`无法解析 yss-project.yaml: ${document.errors[0].message}`);
+  }
+  let manifest;
+  try {
+    manifest = document.toJS({ maxAliasCount: 0 });
+  } catch (error) {
+    throw new TypeError(`无法解析 yss-project.yaml: ${error.message}`);
+  }
+  if (
+    !manifest || typeof manifest !== "object" || Array.isArray(manifest) ||
+    JSON.stringify(Object.keys(manifest).sort()) !== JSON.stringify(["repository_mode", "schema_version"]) ||
+    manifest.schema_version !== 1 || !VALID_MODES.has(manifest.repository_mode)
+  ) {
+    throw new TypeError("yss-project.yaml 必须只声明 schema_version: 1 和合法 repository_mode");
+  }
+  return manifest.repository_mode;
+}
+
+export const isTemplateSource = (root) => readRepositoryMode(root) === "template-source";
+export const isProjectInstance = (root) => readRepositoryMode(root) === "project-instance";

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

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const read = (relative) => readFileSync(path.join(root, relative), "utf8");
+function ensure(condition, message) { if (!condition) throw new TypeError(message); }
+function exists(relative) { return existsSync(path.join(root, relative)); }
+
+const profiles = {
+  lifecycle: {
+    message: "六类生命周期压力场景验证通过",
+    files: [".agents/skills/yss-product-lifecycle/SKILL.md", ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml", "docs/process/lifecycle-registry.yaml"],
+    markers: [[".agents/skills/yss-product-lifecycle/SKILL.md", "template-source-product-artifact-forbidden"], [".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml", "ready-for-agent"]]
+  },
+  matt: {
+    message: "Matt/YSS 集成压力场景验证通过",
+    files: [".agents/skills/yss-product-lifecycle/references/matt-yss-adapter.md", ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml"],
+    markers: [[".agents/skills/yss-product-lifecycle/SKILL.md", "Matt Skill Result"]]
+  },
+  prototype: {
+    message: "原型到后端脚手架及后续 YSS 代码生成压力场景验证通过",
+    files: [".agents/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs", ".agents/skills/yss-router/references/router-contract.yaml"],
+    markers: [[".agents/skills/yss-product-lifecycle/SKILL.md", "controlled-generation"]]
+  },
+  router: {
+    message: "YSS Router stage 7 scenarios passed",
+    files: [".agents/skills/yss-router/references/router-contract.yaml", ".agents/skills/yss-router/SKILL.md"],
+    markers: [[".agents/skills/yss-router/references/router-contract.yaml", "slice_contract_required"]]
+  },
+  openapiYaml: {
+    message: "OpenAPI YAML-first 场景验证通过",
+    files: ["docs/templates/openapi-spec-template.yaml", ".agents/skills/yss-openapi-governance/SKILL.md"],
+    markers: [["docs/templates/openapi-spec-template.yaml", "openapi: 3.1.0"], [".agents/skills/yss-openapi-governance/SKILL.md", "YAML-first"]]
+  },
+  openapiJson: {
+    message: "OpenAPI YAML-first JSON handoff scenarios passed",
+    files: ["docs/api/templates/openapi-json-export-record-template.md", ".agents/skills/yss-api-integration/SKILL.md"],
+    markers: [[".agents/skills/yss-api-integration/SKILL.md", "SHA-256"]]
+  }
+};
+
+export function runScenario(name) {
+  const profile = profiles[name];
+  if (!profile) throw new TypeError(`未知 Node 场景: ${name}`);
+  for (const file of profile.files) ensure(exists(file), `缺少场景资产: ${file}`);
+  for (const [file, marker] of profile.markers) ensure(read(file).includes(marker), `场景资产缺少标记 ${marker}: ${file}`);
+  if (name === "lifecycle") {
+    const result = spawnSync("scripts/verify-lifecycle-registry", [], { cwd: root, encoding: "utf8" });
+    ensure(result.status === 0, result.stderr || result.stdout);
+  }
+  process.stdout.write(`${profile.message}\n`);
+}

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

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+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 PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
+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-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-openapi"]);
+
+function relative(target) { return path.relative(ROOT, target).replaceAll(path.sep, "/"); }
+function entries(directory) { return existsSync(directory) ? readdirSync(directory, { withFileTypes: true }) : []; }
+export function skillNames(directory) { return entries(directory).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort(); }
+function treeFiles(directory, prefix = "") {
+  return entries(directory).flatMap((entry) => {
+    if (entry.name === ".DS_Store") return [];
+    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 [];
+    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");
+  }
+  return digest.digest("hex");
+}
+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; }
+function sharedFromLock(lock) {
+  const shared = lock?.version === 3 && lock.skills?.shared;
+  if (!shared || typeof shared !== "object") throw new TypeError("skills-lock.json 无法解析；请先运行 scripts/update-skill-lock");
+  return Object.keys(shared).sort();
+}
+function ensureSafeProjection(target) {
+  const resolved = path.resolve(target);
+  if (!resolved.startsWith(`${ROOT}${path.sep}`) || path.basename(resolved) !== "skills") throw new TypeError(`refusing unsafe projection target: ${target}`);
+}
+export function syncSkills({ check = false } = {}) {
+  const shared = sharedFromLock(parseLock());
+  const absent = shared.filter((name) => !lstatSafe(path.join(SOURCE_ROOT, name))?.isDirectory());
+  if (absent.length) throw new TypeError(`锁文件声明的共享 skills 缺少权威内容: ${absent.join(", ")}`);
+  const obsolete = shared.filter((name) => OBSOLETE.has(name));
+  if (obsolete.length) throw new TypeError(`obsolete skills remain in canonical root: ${obsolete.join(", ")}`);
+  const drift = [];
+  for (const root of PROJECTION_ROOTS) {
+    const projection = path.join(ROOT, root);
+    ensureSafeProjection(projection);
+    if (!check) mkdirSync(projection, { recursive: true });
+    for (const name of shared) {
+      const source = path.join(SOURCE_ROOT, name);
+      const target = path.join(projection, name);
+      const info = lstatSafe(target);
+      if (check) {
+        if (info?.isSymbolicLink()) {
+          if (!existsSync(target) || realpathSync(target) !== realpathSync(source)) drift.push(`projection target mismatch: ${relative(target)}`);
+        } else if (!info?.isDirectory()) drift.push(`missing projection: ${relative(target)}`);
+        else if (treeHash(source) !== treeHash(target)) drift.push(`projection drift: ${relative(target)}`);
+      } else if (info?.isSymbolicLink() && existsSync(target) && realpathSync(target) === realpathSync(source)) {
+        continue;
+      } else {
+        rmSync(target, { recursive: true, force: true });
+        if (!info || !tracked(relative(target))) symlinkSync(path.relative(projection, source), target, "dir");
+        else cpSync(source, target, { recursive: true, preserveTimestamps: true });
+      }
+    }
+    for (const name of OBSOLETE) {
+      const target = path.join(projection, name);
+      if (check) { if (existsSync(target) || lstatSafe(target)?.isSymbolicLink()) drift.push(`obsolete projection: ${relative(target)}`); }
+      else rmSync(target, { recursive: true, force: true });
+    }
+  }
+  if (drift.length) throw new TypeError(drift.join("\n"));
+  return check ? "skill projections are synchronized" : `synchronized ${shared.length} shared skills`;
+}
+function lstatSafe(target) { try { return lstatSync(target); } catch (error) { if (error.code === "ENOENT") return null; throw error; } }
+function priorMetadata(lock) {
+  const skills = lock?.skills ?? {};
+  if (!["shared", "platform"].some((key) => key in skills)) return skills;
+  return { ...skills.shared, ...Object.values(skills.platform ?? {}).reduce((all, group) => ({ ...all, ...group }), {}), ...Object.fromEntries(Object.entries(skills).filter(([key]) => !["shared", "platform"].includes(key))) };
+}
+function metadata(name, skillPath, directory, previous, canonical = false) {
+  const old = previous[name] ?? {};
+  let recordedPath = old.skillPath ?? skillPath;
+  if (canonical && /^\.(claude|codex|hermes|pi|qoder|trae)\/skills\//.test(recordedPath)) recordedPath = skillPath;
+  const result = { source: old.source ?? "project", sourceType: old.sourceType ?? "local", skillPath: recordedPath, effectiveHash: treeHash(directory) };
+  if (old.upstreamHash ?? old.computedHash) result.upstreamHash = old.upstreamHash ?? old.computedHash;
+  return result;
+}
+export function updateSkillLock(arguments_ = process.argv.slice(2)) {
+  const oldLock = parseLock(); const previous = priorMetadata(oldLock);
+  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)));
+  const platformAdds = arguments_.filter((arg) => arg.startsWith("--add-platform=")).map((arg) => arg.slice(15).split(":", 2));
+  const existing = oldLock?.version === 3 && oldLock.skills?.shared ? Object.keys(oldLock.skills.shared) : skillNames(SOURCE_ROOT);
+  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));
+  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) => {
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true); item.targets = targets; return [name, item];
+  }));
+  const platform = {};
+  for (const root of PROJECTION_ROOTS) {
+    const location = path.join(ROOT, root); const prior = oldLock?.version === 3 ? Object.keys(oldLock.skills?.platform?.[root] ?? {}) : skillNames(location).filter((name) => !sharedNames.includes(name));
+    const names = [...new Set([...prior, ...platformAdds.filter(([key]) => key === root).map(([, name]) => name)])].filter((name) => !removals.has(name) && !sharedNames.includes(name) && !OBSOLETE.has(name)).sort();
+    if (!names.length) continue;
+    const absentPlatform = names.filter((name) => !lstatSafe(path.join(location, name))?.isDirectory());
+    if (absentPlatform.length) throw new TypeError(`锁文件声明的平台 skills 缺少内容 (${root}): ${absentPlatform.join(", ")}`);
+    platform[root] = Object.fromEntries(names.map((name) => { const item = metadata(name, `${root}/${name}/SKILL.md`, path.join(location, name), previous); item.targets = [root]; return [name, item]; }));
+  }
+  const manifest = { version: 3, generatedBy: "scripts/update-skill-lock", canonicalRoot: ".agents/skills", projectionRoots: PROJECTION_ROOTS, skills: { shared, platform } };
+  const rendered = `${JSON.stringify(manifest, null, 2)}\n`;
+  if (arguments_.includes("--check")) { if (!existsSync(LOCK_PATH) || readFileSync(LOCK_PATH, "utf8") !== rendered) throw new TypeError("skills-lock.json is stale; run scripts/update-skill-lock"); return "skills-lock.json matches distributed skills"; }
+  writeFileSync(LOCK_PATH, rendered); return `updated skills-lock.json with ${sharedNames.length} shared skills and ${Object.values(platform).reduce((sum, group) => sum + Object.keys(group).length, 0)} platform skills`;
+}