create-yss-spec 2.1.3 → 2.1.5

package/template/scripts/lifecycle-registry.rb

@@ -0,0 +1,194 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+require "json"
+require "digest"
+require "yaml"
+
+module LifecycleRegistry
+  ROOT = Pathname.new(__dir__).join("..").realpath
+  DEFAULT_REGISTRY = ROOT.join("docs/process/lifecycle-registry.yaml")
+  DEFAULT_BASELINE = ROOT.join("docs/process/lifecycle-registry-baseline.json")
+  ID_PATTERN = /\A(stage|gate|artifact|work-unit|evidence)\.[a-z0-9][a-z0-9-]*\z/
+
+  module_function
+
+  def load_registry(path = DEFAULT_REGISTRY)
+    YAML.safe_load(Pathname.new(path).read, permitted_classes: [], aliases: false)
+  rescue Psych::Exception => error
+    raise ArgumentError, "无法解析生命周期注册表: #{error.message}"
+  end
+
+  def validate!(registry, baseline: DEFAULT_BASELINE)
+    required_top_level = %w[schema_version registry_id status id_policy stages gates artifacts work_units evidence]
+    missing = required_top_level - registry.keys
+    raise ArgumentError, "生命周期注册表缺少字段: #{missing.join(', ')}" unless missing.empty?
+    raise ArgumentError, "仅支持 lifecycle registry schema_version: 1" unless registry["schema_version"] == 1
+    raise ArgumentError, "registry_id 必须为 yss.lifecycle" unless registry["registry_id"] == "yss.lifecycle"
+    raise ArgumentError, "status 必须为 shadow 或 active" unless %w[shadow active].include?(registry["status"])
+
+    policy = registry.fetch("id_policy")
+    %w[pattern published_ids_immutable baseline deprecated_ids].each do |key|
+      raise ArgumentError, "id_policy 缺少字段: #{key}" unless policy.key?(key)
+    end
+    raise ArgumentError, "published_ids_immutable 必须为 true" unless policy["published_ids_immutable"] == true
+    raise ArgumentError, "id_policy.pattern 不符合固定命名空间" unless policy["pattern"] == "^(stage|gate|artifact|work-unit|evidence)\\.[a-z0-9][a-z0-9-]*$"
+    raise ArgumentError, "id_policy.baseline 必须指向发布基线" unless policy["baseline"] == "docs/process/lifecycle-registry-baseline.json"
+    raise ArgumentError, "deprecated_ids 必须是数组" unless policy["deprecated_ids"].is_a?(Array)
+
+    ids = {}
+    %w[stages gates artifacts work_units evidence].each do |collection|
+      records = registry.fetch(collection)
+      raise ArgumentError, "#{collection} 必须是非空数组" unless records.is_a?(Array) && !records.empty?
+      records.each do |record|
+        id = record["id"]
+        raise ArgumentError, "#{collection} 中存在无效 ID: #{id.inspect}" unless id.is_a?(String) && id.match?(ID_PATTERN)
+        raise ArgumentError, "生命周期 ID 重复: #{id}" if ids.key?(id)
+        expected_prefix = collection == "work_units" ? "work-unit." : collection.delete_suffix("s") + "."
+        raise ArgumentError, "#{id} 与 #{collection} 类型不匹配" unless id.start_with?(expected_prefix)
+        raise ArgumentError, "#{id} 缺少名称" unless record["name"].is_a?(String) && !record["name"].empty?
+        ids[id] = collection
+      end
+    end
+
+    registry.fetch("gates").each do |gate|
+      require_reference!(ids, gate.fetch("stage"), "#{gate["id"]}.stage")
+      unless ids[gate.fetch("stage")] == "stages"
+        raise ArgumentError, "#{gate["id"]}.stage 必须引用 stage.*"
+      end
+      evidence = gate.fetch("evidence")
+      raise ArgumentError, "#{gate["id"]}.evidence 必须是非空数组" unless evidence.is_a?(Array) && !evidence.empty?
+      evidence.each do |reference|
+        require_reference!(ids, reference, "#{gate["id"]}.evidence")
+        raise ArgumentError, "#{gate["id"]}.evidence 必须引用 evidence.*" unless ids[reference] == "evidence"
+      end
+    end
+
+    registry.fetch("artifacts").each do |artifact|
+      require_reference!(ids, artifact.fetch("stage"), "#{artifact["id"]}.stage")
+      raise ArgumentError, "#{artifact["id"]}.stage 必须引用 stage.*" unless ids[artifact.fetch("stage")] == "stages"
+    end
+    validate_baseline!(registry, ids, Pathname.new(baseline)) if baseline
+    registry
+  end
+
+  def require_reference!(ids, reference, field)
+    raise ArgumentError, "#{field} 引用了不存在的引用: #{reference}" unless ids.key?(reference)
+  end
+
+  def semantic_projection(registry)
+    %w[stages gates artifacts work_units evidence].flat_map do |collection|
+      registry.fetch(collection).map do |record|
+        {
+          "kind" => collection,
+          "record" => canonicalize(record)
+        }
+      end
+    end.sort_by { |entry| entry.fetch("record").fetch("id") }
+  end
+
+  def canonicalize(value)
+    case value
+    when Hash
+      value.keys.sort.to_h { |key| [key, canonicalize(value.fetch(key))] }
+    when Array
+      value.map { |item| canonicalize(item) }
+    else
+      value
+    end
+  end
+
+  def semantic_digest(registry)
+    Digest::SHA256.hexdigest(JSON.generate(semantic_projection(registry)))
+  end
+
+  def validate_baseline!(registry, ids, baseline_path)
+    raise ArgumentError, "缺少生命周期已发布基线: #{baseline_path.relative_path_from(ROOT)}" unless baseline_path.file?
+    baseline = JSON.parse(baseline_path.read)
+    unless baseline["schema_version"] == 1 && baseline["registry_id"] == registry["registry_id"]
+      raise ArgumentError, "生命周期已发布基线版本或 registry_id 不匹配"
+    end
+    published_ids = baseline["published_ids"]
+    raise ArgumentError, "生命周期已发布基线缺少 published_ids" unless published_ids.is_a?(Array) && published_ids.uniq == published_ids
+    published_ids.each do |id|
+      raise ArgumentError, "生命周期已发布基线包含无效 ID: #{id.inspect}" unless id.is_a?(String) && id.match?(ID_PATTERN)
+    end
+
+    active_ids = ids.keys.sort
+    deprecated_ids = registry.fetch("id_policy").fetch("deprecated_ids")
+    unless deprecated_ids.uniq == deprecated_ids && deprecated_ids.all? { |id| published_ids.include?(id) } && (deprecated_ids & active_ids).empty?
+      raise ArgumentError, "deprecated_ids 必须唯一、来自已发布 ID，且不得仍为活跃对象"
+    end
+    expected_active_ids = (published_ids - deprecated_ids).sort
+    raise ArgumentError, "生命周期活跃 ID 与已发布基线不一致；新增、移除或弃用必须先更新发布基线" unless active_ids == expected_active_ids
+    raise ArgumentError, "生命周期稳定 ID 的语义快照已变化；不得复用已发布 ID" unless baseline["semantic_sha256"] == semantic_digest(registry)
+  rescue JSON::ParserError => error
+    raise ArgumentError, "无法解析生命周期已发布基线: #{error.message}"
+  end
+
+  def render_lifecycle_structure(registry)
+    lines = []
+    lines << "<!-- lifecycle-registry:structure:start -->"
+    lines << "> 此结构区由 `docs/process/lifecycle-registry.yaml` 生成。当前为 `#{registry.fetch("status")}` 模式：它校验结构和派生文档，不改变运行时状态 schema 或人工批准语义。"
+    lines << ""
+    lines << "## 1. 主阶段"
+    lines << ""
+    lines << "| 稳定 ID | 阶段 | 目标 | 退出标准 |"
+    lines << "|---|---|---|---|"
+    registry.fetch("stages").each { |stage| lines << "| `#{stage["id"]}` | #{stage["name"]} | #{stage["goal"]} | #{stage["exit_criteria"]} |" }
+    lines << ""
+    lines << "## 2. 生命周期对象"
+    lines << ""
+    lines << "门禁是需要裁决的审查点；产物、工作单元和证据不是门禁的同义词。未命中条件的门禁记录 `not-applicable` 及原因，不生成空文档。"
+    lines << ""
+    lines << "### 2.1 条件门禁"
+    lines << ""
+    lines << "| 稳定 ID | 门禁 | 所属阶段 | 触发条件 | 必须留下的证据 |"
+    lines << "|---|---|---|---|---|"
+    registry.fetch("gates").each do |gate|
+      evidence = gate.fetch("evidence").map { |id| "`#{id}`" }.join("、")
+      lines << "| `#{gate["id"]}` | #{gate["name"]} | `#{gate["stage"]}` | #{gate["trigger"]} | #{evidence} |"
+    end
+    lines << ""
+    lines << "### 2.2 生命周期产物"
+    lines << ""
+    lines << "| 稳定 ID | 产物 | 所属阶段 | 触发条件 |"
+    lines << "|---|---|---|---|"
+    registry.fetch("artifacts").each { |artifact| lines << "| `#{artifact["id"]}` | #{artifact["name"]} | `#{artifact["stage"]}` | #{artifact["trigger"]} |" }
+    lines << ""
+    lines << "### 2.3 执行证据"
+    lines << ""
+    lines << "| 稳定 ID | 证据 | 说明 |"
+    lines << "|---|---|---|"
+    registry.fetch("evidence").each { |evidence| lines << "| `#{evidence["id"]}` | #{evidence["name"]} | #{evidence["description"]} |" }
+    lines << "<!-- lifecycle-registry:structure:end -->"
+    lines.join("\n") + "\n"
+  end
+
+  def render_work_units(registry)
+    lines = []
+    lines << "<!-- lifecycle-registry:work-units:start -->"
+    lines << "> 此表由 `docs/process/lifecycle-registry.yaml` 生成；它只描述 `template-source` 的 Harness 工作单元。"
+    lines << ""
+    lines << "| 稳定 ID | 工作单元 | 输入 | 输出 | 完成条件 |"
+    lines << "|---|---|---|---|---|"
+    registry.fetch("work_units").each do |unit|
+      lines << "| `#{unit["id"]}` | #{unit["name"]} | #{unit["input"]} | #{unit["output"]} | #{unit["completion"]} |"
+    end
+    lines << "<!-- lifecycle-registry:work-units:end -->"
+    lines.join("\n") + "\n"
+  end
+
+  def replace_region!(path, start_marker, end_marker, replacement, check: false)
+    body = path.read
+    expression = /#{Regexp.escape(start_marker)}.*?#{Regexp.escape(end_marker)}\n?/m
+    raise ArgumentError, "派生文档缺少生成区: #{path.relative_path_from(ROOT)}" unless body.match?(expression)
+    expected = body.sub(expression, replacement)
+    if check
+      raise ArgumentError, "派生文档与注册表漂移: #{path.relative_path_from(ROOT)}；运行 scripts/generate-lifecycle-artifacts --write" unless expected == body
+    else
+      path.write(expected)
+    end
+  end
+end

package/template/scripts/sync-skills

@@ -38,6 +38,7 @@ OBSOLETE_SKILLS = %w[
   yss-quality
   yss-sql-condition
   yss-sql-tpl
+  yss-openapi
 ].freeze
 
 def skill_names(root)

package/template/scripts/test-export-yss-skills.rb

@@ -18,6 +18,7 @@ REMOVED_SKILLS = %w[
   yss-quality
   yss-sql-condition
   yss-sql-tpl
+  yss-openapi
 ].freeze
 
 class ExportYssSkillsTest < Minitest::Test
@@ -31,19 +32,21 @@ class ExportYssSkillsTest < Minitest::Test
       stdout, stderr, result = run_export(output)
 
       assert result.success?, "#{stdout}\n#{stderr}"
-      assert_equal 46, Dir.glob(output.join("skills", "*").to_s).count { |path| File.directory?(path) }
+      assert_equal 45, Dir.glob(output.join("skills", "*").to_s).count { |path| File.directory?(path) }
 
       manifest = JSON.parse(output.join(".yss-export-manifest.json").read)
-      assert_equal 46, manifest.fetch("skills").length
-      assert_operator manifest.fetch("generated_files_sha256").length, :>, 46
+      assert_equal 45, manifest.fetch("skills").length
+      assert_operator manifest.fetch("generated_files_sha256").length, :>, 45
+      assert output.join("skills", "yss-prototype-stage", "SKILL.md").file?, "prototype stage contract was not exported"
       REMOVED_SKILLS.each do |skill_name|
         refute output.join("skills", skill_name).exist?, "removed skill was exported: #{skill_name}"
       end
 
       page = JSON.parse(output.join("skills.sh.json").read)
       grouped = page.fetch("groupings").flat_map { |group| group.fetch("skills") }
-      assert_equal 46, grouped.uniq.length
-      assert_equal 46, grouped.length
+      assert_equal 45, grouped.uniq.length
+      assert_equal 45, grouped.length
+      assert_includes grouped, "yss-prototype-stage"
 
       exported_text = Dir.glob(output.join("skills", "**", "*").to_s)
         .select { |path| File.file?(path) }
@@ -51,7 +54,8 @@ class ExportYssSkillsTest < Minitest::Test
         .select(&:valid_encoding?)
         .join("\n")
       REMOVED_SKILLS.each do |skill_name|
-        refute_match(/\b#{Regexp.escape(skill_name)}\b/, exported_text, "removed skill is still referenced: #{skill_name}")
+        pattern = Regexp.new("(?<![a-z0-9-])#{Regexp.escape(skill_name)}(?![a-z0-9-])")
+        refute_match(pattern, exported_text, "removed skill is still referenced: #{skill_name}")
       end
 
       formily_examples = output.join("skills", "yss-formily", "references", "examples.md").read

package/template/scripts/test-lifecycle-registry.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "minitest/autorun"
+require "open3"
+require "pathname"
+require "tmpdir"
+require "yaml"
+
+ROOT = Pathname.new(__dir__).join("..").realpath
+
+class LifecycleRegistryTest < Minitest::Test
+  def run_command(*command)
+    output, status = Open3.capture2e(*command, chdir: ROOT)
+    [output, status]
+  end
+
+  def test_registry_verifier_and_generated_views_are_current
+    output, status = run_command("scripts/verify-lifecycle-registry")
+    assert status.success?, output
+
+    output, status = run_command("scripts/generate-lifecycle-artifacts", "--check")
+    assert status.success?, output
+  end
+
+  def test_verifier_rejects_unknown_cross_reference
+    Dir.mktmpdir("yss-lifecycle-registry") do |directory|
+      registry_path = Pathname.new(directory).join("broken.yaml")
+      registry = YAML.safe_load(ROOT.join("docs/process/lifecycle-registry.yaml").read, aliases: false)
+      registry.fetch("gates").first.fetch("evidence") << "evidence.unknown"
+      registry_path.write(YAML.dump(registry))
+
+      output, status = run_command("scripts/verify-lifecycle-registry", "--registry", registry_path.to_s)
+      refute status.success?, output
+      assert_includes output, "不存在的引用"
+    end
+  end
+
+  def test_verifier_executes_json_schema_and_stable_id_baseline
+    Dir.mktmpdir("yss-lifecycle-registry") do |directory|
+      schema_broken = Pathname.new(directory).join("schema-broken.yaml")
+      semantic_broken = Pathname.new(directory).join("semantic-broken.yaml")
+      registry = YAML.safe_load(ROOT.join("docs/process/lifecycle-registry.yaml").read, aliases: false)
+
+      registry.fetch("stages").first.delete("goal")
+      schema_broken.write(YAML.dump(registry))
+      output, status = run_command("scripts/verify-lifecycle-registry", "--registry", schema_broken.to_s)
+      refute status.success?, output
+      assert_includes output, "JSON Schema 校验失败"
+
+      registry = YAML.safe_load(ROOT.join("docs/process/lifecycle-registry.yaml").read, aliases: false)
+      registry.fetch("gates").first["trigger"] = "被静默改变的语义。"
+      semantic_broken.write(YAML.dump(registry))
+      output, status = run_command("scripts/verify-lifecycle-registry", "--registry", semantic_broken.to_s)
+      refute status.success?, output
+      assert_includes output, "语义快照已变化"
+    end
+  end
+
+  def test_policy_documents_do_not_reintroduce_stale_counts
+    forbidden_count = /\d+\s*个(?:主阶段|门禁|工作单元|职责点)/
+    assert_match forbidden_count, "必须按 8 个主阶段推进"
+
+    [
+      "AGENTS.md",
+      "README.md",
+      "docs/user-guide/产品生命周期工作流.md",
+      ".agents/skills/yss-product-lifecycle/SKILL.md"
+    ].each do |relative_path|
+      body = ROOT.join(relative_path).read
+      refute_match(forbidden_count, body, relative_path)
+    end
+  end
+end

package/template/scripts/update-skill-lock

@@ -37,6 +37,7 @@ OBSOLETE_SKILLS = %w[
   yss-quality
   yss-sql-condition
   yss-sql-tpl
+  yss-openapi
 ].freeze
 LOCK_GROUPS = %w[shared platform].freeze
 GIT_WORKTREE = system(

package/template/scripts/verify-governance-release

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "yaml"
+
+ROOT = Pathname.new(__dir__).join("..").realpath
+failures = []
+
+{
+  "docs/architecture/templates/system-overview-design-template.md" => "已明确的认证、授权、租户隔离、敏感数据或合规行为",
+  "docs/architecture/templates/tech-design-template.md" => "已明确的认证、授权、租户隔离、敏感数据或合规行为"
+}.each do |relative_path, marker|
+  body = ROOT.join(relative_path).read
+  failures << "#{relative_path} 缺少条件性安全/权限架构承载" unless body.include?(marker)
+end
+
+{
+  "docs/adr/0003-machine-readable-lifecycle-registry.md" => "状态：部分实施（Phase 1）",
+  "docs/adr/0004-split-lifecycle-and-router-registry-domains.md" => "状态：proposed",
+  "docs/adr/0005-cross-repository-ecosystem-release-manifest.md" => "状态：proposed",
+  "docs/adr/0006-stable-lifecycle-ids-and-generated-structure.md" => "状态：部分实施（Phase 1）",
+  "docs/adr/0007-separate-skill-routing-registry-from-integrity-lock.md" => "状态：proposed"
+}.each do |relative_path, marker|
+  body = ROOT.join(relative_path).read
+  failures << "#{relative_path} 未声明当前实现状态" unless body.include?(marker)
+end
+
+scenario_verifier = ROOT.join("scripts/verify-lifecycle-scenarios").read
+failures << "生命周期场景未校验稳定 ID 映射" unless scenario_verifier.include?("ROUTE_REGISTRY_IDS")
+
+unless failures.empty?
+  warn failures.join("\n")
+  exit 1
+end
+
+warn failures.join("\n") unless failures.empty?
+exit(failures.empty? ? 0 : 1)

package/template/scripts/verify-lifecycle-registry

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "optparse"
+require_relative "lifecycle-registry"
+
+options = { registry: LifecycleRegistry::DEFAULT_REGISTRY }
+OptionParser.new do |parser|
+  parser.on("--registry PATH", "使用指定注册表") { |path| options[:registry] = Pathname.new(path) }
+end.parse!
+
+begin
+  schema_path = LifecycleRegistry::ROOT.join("docs/process/schemas/lifecycle-registry.schema.json")
+  schema = JSON.parse(schema_path.read)
+  raise ArgumentError, "生命周期注册表 JSON Schema 缺少 schema_version 约束" unless schema.dig("properties", "schema_version", "const") == 1
+  json_schema_program = <<~'PYTHON'
+    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)
+  PYTHON
+  registry_json = JSON.generate(LifecycleRegistry.load_registry(options[:registry]))
+  output, status = Open3.capture2e("python3", "-c", json_schema_program, schema_path.to_s, stdin_data: registry_json)
+  raise ArgumentError, "JSON Schema 校验失败: #{output}" unless status.success?
+  registry = LifecycleRegistry.validate!(LifecycleRegistry.load_registry(options[:registry]))
+
+  if options[:registry] == LifecycleRegistry::DEFAULT_REGISTRY
+    command = [LifecycleRegistry::ROOT.join("scripts/generate-lifecycle-artifacts").to_s, "--check"]
+    output, status = Open3.capture2e(*command, chdir: LifecycleRegistry::ROOT)
+    raise ArgumentError, output unless status.success?
+
+    tracked_sources = %w[docs/process/lifecycle-registry.yaml docs/process/lifecycle-registry-baseline.json docs/process/schemas/lifecycle-registry.schema.json]
+    tracked_sources.each do |relative_path|
+      _output, ignored = Open3.capture2e("git", "check-ignore", "-q", relative_path, chdir: LifecycleRegistry::ROOT)
+      raise ArgumentError, "权威注册表资产不得被 Git 忽略: #{relative_path}" if ignored.success?
+    end
+
+    stale_count_paths = %w[AGENTS.md README.md docs/user-guide/产品生命周期工作流.md .agents/skills/yss-product-lifecycle/SKILL.md docs/process/lifecycle-artifact-map.md docs/process/harness-work-unit-map.md]
+    stale_count_paths.each do |relative_path|
+      body = LifecycleRegistry::ROOT.join(relative_path).read
+      if body.match?(/\d+\s*个(?:主阶段|门禁|工作单元|职责点)/)
+        raise ArgumentError, "#{relative_path} 不得手工声明生命周期对象数量；请引用 lifecycle-registry.yaml"
+      end
+    end
+
+    public_skills = JSON.parse(LifecycleRegistry::ROOT.join("yss-public-skills.json").read)
+    groups = public_skills.fetch("groupings").to_h { |group| [group.fetch("title"), group.fetch("skills")] }
+    raise ArgumentError, "yss-web-controller 必须在后端分组" unless groups.fetch("后端").include?("yss-web-controller")
+    raise ArgumentError, "yss-web-controller 不得在前端分组" if groups.fetch("前端").include?("yss-web-controller")
+  end
+
+  puts "生命周期注册表验证通过（#{registry.fetch("status")}）"
+rescue ArgumentError, KeyError, JSON::ParserError => error
+  warn "生命周期注册表验证失败: #{error.message}"
+  exit 1
+end