create-yss-spec 2.1.5 → 2.1.6

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`;
+}

package/template/scripts/node-generate-lifecycle-artifacts.mjs

@@ -0,0 +1,33 @@
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_REGISTRY, ROOT, loadRegistry, renderLifecycleStructure, renderWorkUnits, replaceRegion, validateRegistry } from "./lib/lifecycle-registry.mjs";
+import { isTemplateSource } from "./lib/repository-mode.mjs";
+
+try {
+  const { values } = parseArgs({
+    options: { check: { type: "boolean" }, write: { type: "boolean" }, registry: { type: "string" } },
+    strict: true
+  });
+  if (values.check && values.write) throw new TypeError("--check 与 --write 不能同时使用");
+  const registryPath = values.registry ? path.resolve(values.registry) : DEFAULT_REGISTRY;
+  const registry = validateRegistry(loadRegistry(registryPath));
+  const targets = [[
+    path.join(ROOT, "docs/process/lifecycle-artifact-map.md"),
+    "<!-- lifecycle-registry:structure:start -->",
+    "<!-- lifecycle-registry:structure:end -->",
+    renderLifecycleStructure(registry)
+  ]];
+  if (isTemplateSource(ROOT)) {
+    targets.push([
+      path.join(ROOT, ".template-source/derived/harness-work-unit-map.md"),
+      "<!-- lifecycle-registry:work-units:start -->",
+      "<!-- lifecycle-registry:work-units:end -->",
+      renderWorkUnits(registry)
+    ]);
+  }
+  for (const [target, start, end, rendered] of targets) replaceRegion(target, start, end, rendered, { check: Boolean(values.check) });
+  process.stdout.write(`${values.check ? "生命周期派生产物与注册表一致" : "生命周期派生产物已更新"}\n`);
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/node-verify-lifecycle-registry.mjs

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { DEFAULT_REGISTRY, ROOT, loadRegistry, validateRegistry } from "./lib/lifecycle-registry.mjs";
+import { isTemplateSource } from "./lib/repository-mode.mjs";
+
+const schemaValidator = String.raw`
+import json
+import sys
+from jsonschema import Draft202012Validator
+
+with open(sys.argv[1], encoding="utf-8") as schema_file:
+    schema = json.load(schema_file)
+registry = json.load(sys.stdin)
+errors = sorted(Draft202012Validator(schema).iter_errors(registry), key=lambda error: list(error.absolute_path))
+if errors:
+    for error in errors:
+        location = ".".join(str(part) for part in error.absolute_path) or "<root>"
+        print(f"{location}: {error.message}", file=sys.stderr)
+    sys.exit(1)
+`;
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, { cwd: ROOT, encoding: "utf8", ...options });
+}
+
+try {
+  const { values } = parseArgs({ options: { registry: { type: "string" } }, strict: true });
+  const registryPath = values.registry ? path.resolve(values.registry) : DEFAULT_REGISTRY;
+  const schemaPath = path.join(ROOT, "docs/process/schemas/lifecycle-registry.schema.json");
+  const schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+  if (schema.properties?.schema_version?.const !== 1) throw new TypeError("生命周期注册表 JSON Schema 缺少 schema_version 约束");
+  const registry = loadRegistry(registryPath);
+  const schemaResult = run("python3", ["-c", schemaValidator, schemaPath], { input: JSON.stringify(registry) });
+  if (schemaResult.status !== 0) throw new TypeError(`JSON Schema 校验失败: ${schemaResult.stdout}${schemaResult.stderr}`);
+  validateRegistry(registry);
+  if (registryPath === DEFAULT_REGISTRY) {
+    const generated = run("node", ["scripts/node-generate-lifecycle-artifacts.mjs", "--check"]);
+    if (generated.status !== 0) throw new TypeError(`${generated.stdout}${generated.stderr}`.trim());
+    for (const relativePath of ["docs/process/lifecycle-registry.yaml", "docs/process/lifecycle-registry-baseline.json", "docs/process/schemas/lifecycle-registry.schema.json"]) {
+      const ignored = run("git", ["check-ignore", "-q", relativePath]);
+      if (ignored.status === 0) throw new TypeError(`权威注册表资产不得被 Git 忽略: ${relativePath}`);
+    }
+    const stalePaths = ["AGENTS.md", "README.md", "docs/user-guide/产品生命周期工作流.md", ".agents/skills/yss-product-lifecycle/SKILL.md", "docs/process/lifecycle-artifact-map.md"];
+    if (isTemplateSource(ROOT)) stalePaths.push(".template-source/derived/harness-work-unit-map.md");
+    for (const relativePath of stalePaths) {
+      if (/\d+\s*个(?:主阶段|门禁|工作单元|职责点)/.test(readFileSync(path.join(ROOT, relativePath), "utf8"))) {
+        throw new TypeError(`${relativePath} 不得手工声明生命周期对象数量；请引用 lifecycle-registry.yaml`);
+      }
+    }
+    const publicSkills = JSON.parse(readFileSync(path.join(ROOT, "yss-public-skills.json"), "utf8"));
+    const groups = new Map(publicSkills.groupings.map((group) => [group.title, group.skills]));
+    if (!groups.get("后端")?.includes("yss-web-controller")) throw new TypeError("yss-web-controller 必须在后端分组");
+    if (groups.get("前端")?.includes("yss-web-controller")) throw new TypeError("yss-web-controller 不得在前端分组");
+  }
+  process.stdout.write(`生命周期注册表验证通过（${registry.status}）\n`);
+} catch (error) {
+  process.stderr.write(`生命周期注册表验证失败: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/template/scripts/repository-mode

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { readRepositoryMode } from "./lib/repository-mode.mjs";
+
+try {
+  process.stdout.write(`${readRepositoryMode(process.cwd())}\n`);
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}