create-yss-spec 1.1.3 → 2.0.0

package/template/docs/user-guide/spec-ticket-migration-guide.md

@@ -0,0 +1,35 @@
+# Spec / Ticket 迁移指南
+
+本文面向从旧版模板升级的仓库。新模板采用一次性破坏性迁移，不保留旧 skill 的转发别名；迁移完成后应运行 `scripts/verify-template`。
+
+## 名称映射
+
+| 旧入口或路径 | 新入口或路径 |
+|---|---|
+| `to-prd` | `to-spec` |
+| `to-issues` | `to-tickets` |
+| `docs/templates/prd-template.md` | `docs/templates/spec-template.md` |
+| `docs/templates/vertical-slice-issue-template.md` | `docs/templates/vertical-slice-ticket-template.md` |
+| `docs/requirements/issues/` | `docs/requirements/tickets/` |
+| `docs/requirements/<feature>-prd.md` | `docs/requirements/<feature>-spec.md` |
+
+旧文档中的 PRD 可继续作为历史事实保留，但新建和继续维护的规格资产应迁移为 Spec。GitHub Issues 与 GitLab Issues 仍是平台产品名称；领域工作单元统一称为 Ticket。
+
+## 状态迁移
+
+- Spec 初稿、产品设计、原型和 OpenAPI Draft 使用 `ready-for-human`。
+- 需求与契约冻结后，先创建功能父 Ticket，再创建垂直切片子 Ticket。
+- 只有必要门禁已通过、依赖已解除且可直接实现的垂直切片 Ticket 使用 `ready-for-agent`。
+
+## 升级步骤
+
+1. 在根目录添加 `yss-project.yaml`，明确 `repository_mode`。
+2. 重命名旧规格、模板和本地任务目录，并修正 Markdown 链接。
+3. 删除所有 Agent root 中的旧 skill 目录，不创建兼容别名。
+4. 只在 `.agents/skills` 修改共享技能，运行 `scripts/sync-skills` 生成投影。
+5. 运行 `scripts/update-skill-lock` 更新完整树哈希。
+6. 运行 `scripts/verify-template`；修复全部结构、语义、压力场景和链接错误后再进入发布审查。
+
+## 外部初始化 CLI
+
+`create-yss-spec` 必须在初始化和升级时写入正确的 `repository_mode`，并执行等价的路径迁移与集成测试。模板仓库与 CLI 仓库未共同通过集成验证前，不得单独声明新版模板可发布。

package/template/scripts/sync-skills

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+require "pathname"
+
+ROOT = Pathname.new(__dir__).join("..").realpath
+SOURCE_ROOT = ROOT.join(".agents/skills")
+LOCK_PATH = ROOT.join("skills-lock.json")
+PROJECTION_ROOTS = %w[
+  .claude/skills
+  .codex/skills
+  .hermes/skills
+  .pi/skills
+  .trae/skills
+].freeze
+OBSOLETE_SKILLS = %w[to-prd to-issues].freeze
+
+def skill_names(root)
+  root.children.select(&:directory?).map { |item| item.basename.to_s }.sort
+end
+
+def shared_skill_names
+  manifest = JSON.parse(LOCK_PATH.read)
+  shared = manifest.dig("skills", "shared")
+  return shared.keys.sort if manifest["version"] == 3 && shared.is_a?(Hash)
+
+  skill_names(SOURCE_ROOT) - OBSOLETE_SKILLS
+rescue JSON::ParserError, Errno::ENOENT
+  warn "skills-lock.json 无法解析；请先运行 scripts/update-skill-lock"
+  exit 1
+end
+
+def tree_hash(root)
+  digest = Digest::SHA256.new
+  root.glob("**/*", File::FNM_DOTMATCH)
+      .reject { |item| item.directory? || item.basename.to_s == ".DS_Store" }
+      .sort_by { |item| item.relative_path_from(root).to_s }
+      .each do |item|
+    relative = item.relative_path_from(root).to_s
+    digest << relative << "\0" << item.binread << "\0"
+  end
+  digest.hexdigest
+end
+
+def validate_target!(target)
+  expanded = target.expand_path
+  expected_prefix = ROOT.join(".").expand_path.to_s + File::SEPARATOR
+  return if expanded.to_s.start_with?(expected_prefix) && expanded.basename.to_s == "skills"
+
+  warn "refusing unsafe projection target: #{target}"
+  exit 2
+end
+
+def tracked_projection?(target)
+  relative = target.relative_path_from(ROOT).to_s
+  !IO.popen(["git", "ls-files", "-z", "--", relative], &:read).empty?
+end
+
+check_only = ARGV.include?("--check")
+shared = shared_skill_names
+missing_from_source = shared.reject { |skill_name| SOURCE_ROOT.join(skill_name).directory? }
+unless missing_from_source.empty?
+  warn "锁文件声明的共享 skills 缺少权威内容: #{missing_from_source.join(', ')}"
+  exit 1
+end
+obsolete_in_source = shared & OBSOLETE_SKILLS
+unless obsolete_in_source.empty?
+  warn "obsolete skills remain in canonical root: #{obsolete_in_source.join(', ')}"
+  exit 1
+end
+
+drift = []
+
+PROJECTION_ROOTS.each do |relative_root|
+  projection_root = ROOT.join(relative_root)
+  validate_target!(projection_root)
+  FileUtils.mkdir_p(projection_root) unless check_only
+
+  shared.each do |skill_name|
+    source = SOURCE_ROOT.join(skill_name)
+    target = projection_root.join(skill_name)
+
+    if check_only
+      if target.symlink?
+        drift << "projection target mismatch: #{target.relative_path_from(ROOT)}" unless target.realpath == source.realpath
+      elsif !target.directory?
+        drift << "missing projection: #{target.relative_path_from(ROOT)}"
+      elsif tree_hash(source) != tree_hash(target)
+        drift << "projection drift: #{target.relative_path_from(ROOT)}"
+      end
+      next
+    end
+
+    if target.symlink?
+      next if target.realpath == source.realpath
+
+      FileUtils.rm_f(target)
+      FileUtils.ln_s(source.relative_path_from(projection_root), target)
+    elsif !tracked_projection?(target)
+      FileUtils.rm_rf(target)
+      FileUtils.ln_s(source.relative_path_from(projection_root), target)
+    else
+      FileUtils.rm_rf(target)
+      FileUtils.cp_r(source, target, preserve: true)
+    end
+  end
+
+  OBSOLETE_SKILLS.each do |skill_name|
+    target = projection_root.join(skill_name)
+    if check_only
+      drift << "obsolete projection: #{target.relative_path_from(ROOT)}" if target.exist?
+    else
+      FileUtils.rm_rf(target)
+    end
+  end
+end
+
+unless drift.empty?
+  warn drift.join("\n")
+  exit 1
+end
+
+puts check_only ? "skill projections are synchronized" : "synchronized #{shared.length} shared skills"

package/template/scripts/update-skill-lock

@@ -0,0 +1,202 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "pathname"
+
+ROOT = Pathname.new(__dir__).join("..").realpath
+LOCK_PATH = ROOT.join("skills-lock.json")
+SHARED_ROOT = ROOT.join(".agents/skills")
+PROJECTION_ROOTS = %w[
+  .claude/skills
+  .codex/skills
+  .hermes/skills
+  .pi/skills
+  .trae/skills
+].freeze
+GIT_WORKTREE = system(
+  "git",
+  "rev-parse",
+  "--is-inside-work-tree",
+  out: File::NULL,
+  err: File::NULL
+)
+
+def tracked_skill_names(relative_root)
+  return [] unless GIT_WORKTREE
+
+  IO.popen(
+    ["git", "ls-files", "-z", "--", relative_root],
+    err: File::NULL,
+    &:read
+  ).split("\0").map { |item| item.split("/")[2] }.compact.uniq
+end
+
+def skill_names(root)
+  return [] unless root.directory?
+
+  root.children.select(&:directory?).map { |item| item.basename.to_s }.sort
+end
+
+def tree_hash(root)
+  digest = Digest::SHA256.new
+  root.glob("**/*", File::FNM_DOTMATCH)
+      .reject { |item| item.directory? || item.basename.to_s == ".DS_Store" }
+      .sort_by { |item| item.relative_path_from(root).to_s }
+      .each do |item|
+    relative = item.relative_path_from(root).to_s
+    digest << relative << "\0" << item.binread << "\0"
+  end
+  digest.hexdigest
+end
+
+def old_metadata
+  return {} unless LOCK_PATH.file?
+
+  parsed = JSON.parse(LOCK_PATH.read)
+  skills = parsed.fetch("skills", {})
+  return skills unless skills.key?("shared") || skills.key?("platform")
+
+  shared = skills.fetch("shared", {})
+  platform = skills.fetch("platform", {}).values.reduce({}) { |all, group| all.merge(group) }
+  shared.merge(platform)
+rescue JSON::ParserError
+  {}
+end
+
+def existing_shared_names
+  return nil unless LOCK_PATH.file?
+
+  parsed = JSON.parse(LOCK_PATH.read)
+  shared = parsed.dig("skills", "shared")
+  return shared.keys.sort if parsed["version"] == 3 && shared.is_a?(Hash)
+
+  nil
+rescue JSON::ParserError
+  nil
+end
+
+def existing_platform_inventory
+  return nil unless LOCK_PATH.file?
+
+  parsed = JSON.parse(LOCK_PATH.read)
+  platform = parsed.dig("skills", "platform")
+  return nil unless parsed["version"] == 3 && platform.is_a?(Hash)
+
+  platform.transform_values { |skills| skills.keys.sort }
+rescue JSON::ParserError
+  nil
+end
+
+def metadata_for(skill_name, skill_path, target_root, previous)
+  old = previous.fetch(skill_name, {})
+  metadata = {
+    "source" => old.fetch("source", "project"),
+    "sourceType" => old.fetch("sourceType", "local"),
+    "skillPath" => old.fetch("skillPath", skill_path),
+    "effectiveHash" => tree_hash(target_root)
+  }
+  upstream_hash = old["upstreamHash"] || old["computedHash"]
+  metadata["upstreamHash"] = upstream_hash if upstream_hash
+  metadata
+end
+
+previous = old_metadata
+add_names = ARGV.grep(/\A--add=/).map { |item| item.split("=", 2).last }
+remove_names = ARGV.grep(/\A--remove=/).map { |item| item.split("=", 2).last }
+platform_additions = ARGV.grep(/\A--add-platform=/).map do |item|
+  item.split("=", 2).last.split(":", 2)
+end
+shared_names = existing_shared_names || skill_names(SHARED_ROOT)
+shared_names = ((shared_names + add_names).uniq - remove_names).sort
+
+missing_shared = shared_names.reject { |skill_name| SHARED_ROOT.join(skill_name).directory? }
+unless missing_shared.empty?
+  warn "锁文件声明的共享 skills 缺少权威内容: #{missing_shared.join(', ')}"
+  exit 1
+end
+
+tracked_shared_names = tracked_skill_names(".agents/skills")
+obsolete_names = %w[to-prd to-issues]
+unlocked_tracked = tracked_shared_names - shared_names - obsolete_names
+unless unlocked_tracked.empty?
+  warn "发现未登记到 skills-lock.json 的已跟踪共享 skills: #{unlocked_tracked.sort.join(', ')}"
+  warn "确认新增后运行 scripts/update-skill-lock --add=<skill-name>"
+  exit 1
+end
+
+all_targets = [".agents/skills", *PROJECTION_ROOTS]
+
+shared = shared_names.to_h do |skill_name|
+  skill_root = SHARED_ROOT.join(skill_name)
+  metadata = metadata_for(
+    skill_name,
+    ".agents/skills/#{skill_name}/SKILL.md",
+    skill_root,
+    previous
+  )
+  metadata["targets"] = all_targets
+  [skill_name, metadata]
+end
+
+existing_platform = existing_platform_inventory
+platform = {}
+PROJECTION_ROOTS.each do |relative_root|
+  target_root = ROOT.join(relative_root)
+  default_names = skill_names(target_root) - shared_names
+  platform_names = existing_platform ? existing_platform.fetch(relative_root, []) : default_names
+  additions = platform_additions.select { |root_name, _| root_name == relative_root }.map(&:last)
+  platform_names = ((platform_names + additions).uniq - remove_names - shared_names).sort
+
+  missing_platform = platform_names.reject { |skill_name| target_root.join(skill_name).directory? }
+  unless missing_platform.empty?
+    warn "锁文件声明的平台 skills 缺少内容 (#{relative_root}): #{missing_platform.join(', ')}"
+    exit 1
+  end
+
+  tracked_platform_names = tracked_skill_names(relative_root)
+  unlocked_platform = tracked_platform_names - shared_names - platform_names - obsolete_names
+  unless unlocked_platform.empty?
+    warn "发现未登记的平台 skills (#{relative_root}): #{unlocked_platform.sort.join(', ')}"
+    warn "确认新增后运行 scripts/update-skill-lock --add-platform=#{relative_root}:<skill-name>"
+    exit 1
+  end
+
+  next if platform_names.empty?
+
+  platform[relative_root] = platform_names.to_h do |skill_name|
+    skill_root = target_root.join(skill_name)
+    metadata = metadata_for(
+      skill_name,
+      "#{relative_root}/#{skill_name}/SKILL.md",
+      skill_root,
+      previous
+    )
+    metadata["targets"] = [relative_root]
+    [skill_name, metadata]
+  end
+end
+
+manifest = {
+  "version" => 3,
+  "generatedBy" => "scripts/update-skill-lock",
+  "canonicalRoot" => ".agents/skills",
+  "projectionRoots" => PROJECTION_ROOTS,
+  "skills" => {
+    "shared" => shared,
+    "platform" => platform
+  }
+}
+rendered = JSON.pretty_generate(manifest) + "\n"
+
+if ARGV.include?("--check")
+  unless LOCK_PATH.file? && LOCK_PATH.read == rendered
+    warn "skills-lock.json is stale; run scripts/update-skill-lock"
+    exit 1
+  end
+  puts "skills-lock.json matches distributed skills"
+else
+  LOCK_PATH.write(rendered)
+  puts "updated skills-lock.json with #{shared.length} shared skills and #{platform.values.sum(&:length)} platform skills"
+end

package/template/scripts/verify-lifecycle-scenarios

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "pathname"
+
+ROOT = Pathname.new(__dir__).join("..").realpath
+
+def route(facts)
+  if facts.fetch(:repository_mode) == "template-source"
+    return %w[
+      impact-assessment
+      ssot-update
+      skill-projection-sync
+      pressure-scenarios
+      fresh-verification
+      independent-review
+    ]
+  end
+
+  gates = %w[impact-assessment tracker-sync fresh-verification]
+  return gates if facts.fetch(:scale) == :small && !facts.fetch(:high_risk)
+
+  gates.concat(%w[spec product-overview functional-architecture])
+
+  if facts.fetch(:ui_impact)
+    gates.concat(%w[
+      low-fidelity-prototype
+      state-matrix
+      high-fidelity-html-prototype
+      user-confirmation
+    ])
+  end
+
+  gates.concat(%w[openapi-draft design-review openapi-freeze]) if facts.fetch(:api_impact)
+
+  if facts.fetch(:backend_impact) || facts.fetch(:high_risk)
+    gates.concat(%w[engineering-baseline architecture-review])
+  end
+
+  gates << "data-architecture" if facts.fetch(:data_impact)
+  gates << "spec-delta" if facts.fetch(:existing_frozen_baseline) && facts.fetch(:high_risk)
+  gates.concat(%w[parent-ticket vertical-slice-tickets])
+  gates.uniq
+end
+
+scenarios = [
+  {
+    name: "小文案调整",
+    facts: {
+      repository_mode: "project-instance", scale: :small, high_risk: false,
+      ui_impact: false, api_impact: false, backend_impact: false,
+      data_impact: false, existing_frozen_baseline: true
+    },
+    required: %w[impact-assessment tracker-sync fresh-verification],
+    forbidden: %w[spec product-overview spec-delta high-fidelity-html-prototype]
+  },
+  {
+    name: "纯后端新功能",
+    facts: {
+      repository_mode: "project-instance", scale: :new_module, high_risk: false,
+      ui_impact: false, api_impact: true, backend_impact: true,
+      data_impact: false, existing_frozen_baseline: false
+    },
+    required: %w[spec product-overview functional-architecture openapi-draft engineering-baseline parent-ticket vertical-slice-tickets],
+    forbidden: %w[low-fidelity-prototype state-matrix high-fidelity-html-prototype user-confirmation spec-delta]
+  },
+  {
+    name: "有 UI 的新功能",
+    facts: {
+      repository_mode: "project-instance", scale: :new_module, high_risk: false,
+      ui_impact: true, api_impact: true, backend_impact: true,
+      data_impact: false, existing_frozen_baseline: false
+    },
+    required: %w[spec product-overview low-fidelity-prototype state-matrix high-fidelity-html-prototype user-confirmation openapi-freeze vertical-slice-tickets],
+    forbidden: %w[spec-delta]
+  },
+  {
+    name: "既有冻结基线的高风险变更",
+    facts: {
+      repository_mode: "project-instance", scale: :medium, high_risk: true,
+      ui_impact: false, api_impact: true, backend_impact: true,
+      data_impact: true, existing_frozen_baseline: true
+    },
+    required: %w[spec product-overview spec-delta openapi-draft data-architecture architecture-review vertical-slice-tickets],
+    forbidden: %w[high-fidelity-html-prototype]
+  },
+  {
+    name: "模板源流程修订",
+    facts: {
+      repository_mode: "template-source", scale: :process, high_risk: true,
+      ui_impact: false, api_impact: false, backend_impact: false,
+      data_impact: false, existing_frozen_baseline: false
+    },
+    required: %w[impact-assessment ssot-update skill-projection-sync pressure-scenarios fresh-verification independent-review],
+    forbidden: %w[spec product-overview openapi-draft spec-delta vertical-slice-tickets]
+  }
+].freeze
+
+failures = []
+
+scenarios.each do |scenario|
+  result = route(scenario.fetch(:facts))
+  missing = scenario.fetch(:required) - result
+  unexpected = scenario.fetch(:forbidden) & result
+  failures << "#{scenario.fetch(:name)} 缺少门禁: #{missing.join(', ')}" unless missing.empty?
+  failures << "#{scenario.fetch(:name)} 错误触发: #{unexpected.join(', ')}" unless unexpected.empty?
+end
+
+semantic_markers = {
+  "AGENTS.md" => [
+    "21 个门禁全部是条件强制门禁",
+    "只要进入 Spec 基线",
+    "只有存在 UI 影响时",
+    "Spec Delta 只记录相对既有冻结 Spec 基线",
+    "template-source"
+  ],
+  "docs/process/harness-process-tailoring.md" => [
+    "全新产品 / 模块",
+    "不生成空文档",
+    "最近可信阶段"
+  ]
+}.freeze
+
+semantic_markers.each do |relative_path, markers|
+  body = ROOT.join(relative_path).read
+  markers.each do |marker|
+    failures << "#{relative_path} 缺少语义标记: #{marker}" unless body.include?(marker)
+  end
+end
+
+unless failures.empty?
+  warn failures.join("\n")
+  exit 1
+end
+
+puts "五类生命周期压力场景验证通过"