spectra-cli 4.1.1

package/plugins/spec-driver/lib/orchestrator.mjs

@@ -0,0 +1,280 @@
+/**
+ * orchestrator.mjs
+ * Orchestrator 类：统一编排器，加载 orchestration.yaml 并执行 Phase 序列
+ *
+ * 4-tier Gate 优先级：user_config > hard_gate > gate_policy > yaml_default
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { parseYamlDocument } from '../scripts/lib/simple-yaml.mjs';
+import { generateFallbackConfig } from './orchestrator-fallback.mjs';
+import { orchestrationBaseSchema, formatZodIssue } from '../contracts/orchestration-schema.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export class Orchestrator {
+  /**
+   * @param {Object} userConfig - 用户配置（来自 spec-driver.config.yaml）
+   * @param {string} mode - 运行模式
+   * @param {Object} context - 项目上下文
+   * @param {Object} [options={}] - 可选扩展选项（T-012，D-PLAN-6）
+   * @param {Object} [options.preloadedConfig] - 预加载好的 merged orchestration config（由 resolveOrchestrationConfig 提供）。
+   *   存在时直接使用，跳过 loadAndValidateConfig() 文件读取，防止 CLI 读取两次 YAML 且确保使用合并后的 config。
+   *   不传时行为与迁移前完全一致（向后兼容）。
+   */
+  constructor(userConfig, mode, context = {}, options = {}) {
+    this.userConfig = userConfig || {};
+    this.mode = mode;
+    this.context = context;
+    this.logger = context.logger || defaultLogger;
+
+    if (options.preloadedConfig) {
+      // 使用预加载的 merged config，绕过文件读取（D-PLAN-6 关键陷阱防御）
+      this.config = options.preloadedConfig;
+      this.isFallback = false;
+    } else {
+      this.loadAndValidateConfig();
+    }
+
+    this.buildGateBehaviorMap();
+    this.buildPhaseMap();
+    this.buildParallelGroupMap();
+  }
+
+  /** @private */
+  loadAndValidateConfig() {
+    const configPath = path.join(__dirname, '..', 'config', 'orchestration.yaml');
+
+    try {
+      if (!fs.existsSync(configPath)) {
+        this.logger.warn('[ORCHESTRATOR] orchestration.yaml not found, using fallback');
+        this.config = generateFallbackConfig();
+        this.isFallback = true;
+        return;
+      }
+
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const parsed = parseYamlDocument(content);
+
+      // 使用 orchestrationBaseSchema.safeParse 替代手写校验（CL-016，T-011）
+      const zodResult = orchestrationBaseSchema.safeParse(parsed);
+      if (!zodResult.success) {
+        const issues = zodResult.error.issues.map(formatZodIssue).join('; ');
+        this.logger.error(`[ORCHESTRATOR] Config validation failed: ${issues}`);
+        this.config = generateFallbackConfig();
+        this.isFallback = true;
+        return;
+      }
+
+      this.config = zodResult.data;
+      this.isFallback = false;
+    } catch (error) {
+      this.logger.error(`[ORCHESTRATOR] Failed to load config: ${error.message}`);
+      this.config = generateFallbackConfig();
+      this.isFallback = true;
+    }
+  }
+
+  /**
+   * 构建 Gate 行为映射表
+   * 4-tier 优先级：user_config > hard_gate > gate_policy > yaml_default
+   * @private
+   */
+  buildGateBehaviorMap() {
+    this.gateBehaviorMap = {};
+    const policy = this.userConfig.gate_policy || 'balanced';
+    const userGates = this.userConfig.gates || {};
+    const configGates = this.config.gates || {};
+
+    for (const [gateId, gateDef] of Object.entries(configGates)) {
+      const isHardGate =
+        Array.isArray(gateDef.hard_gate_modes) &&
+        gateDef.hard_gate_modes.includes(this.mode);
+
+      let behavior, source;
+
+      if (isHardGate) {
+        behavior = 'always';
+        source = 'hard_gate';
+      } else if (userGates[gateId]?.pause) {
+        behavior = userGates[gateId].pause;
+        source = 'user_config';
+      } else {
+        const policyDefault = getDefaultBehaviorForPolicy(policy, gateId);
+        if (policyDefault !== null) {
+          behavior = policyDefault;
+          source = 'gate_policy';
+        } else {
+          behavior = gateDef.default_behavior || 'on_failure';
+          source = 'yaml_default';
+        }
+      }
+
+      this.gateBehaviorMap[gateId] = {
+        behavior, source, severity: gateDef.severity,
+        isHardGate, type: gateDef.type, description: gateDef.description,
+      };
+    }
+  }
+
+  /** @private */
+  buildPhaseMap() {
+    this.phaseMap = {};
+    const modeConfig = (this.config.modes || {})[this.mode];
+    if (!modeConfig?.phases) {
+      this.logger.error(`[ORCHESTRATOR] Mode '${this.mode}' not found`);
+      return;
+    }
+    modeConfig.phases.forEach((p) => { this.phaseMap[p.id] = p; });
+  }
+
+  /** @private */
+  buildParallelGroupMap() {
+    this.parallelGroupMap = {};
+    for (const [id, def] of Object.entries(this.config.parallel_groups || {})) {
+      this.parallelGroupMap[id] = {
+        id,
+        members: def.members || [],
+        convergencePoint: def.convergence_point,
+        fallbackStrategy: def.fallback_strategy || 'serial_fallback',
+        maxConcurrent: def.max_concurrent || 2,
+        description: def.description || '',
+      };
+    }
+  }
+
+  getPhases() {
+    const modeConfig = (this.config.modes || {})[this.mode];
+    if (!modeConfig?.phases) return [];
+    return modeConfig.phases;
+  }
+
+  getGateBehavior(gateId) {
+    return this.gateBehaviorMap[gateId] || {
+      behavior: 'on_failure', source: 'default',
+      severity: 'non_critical', isHardGate: false,
+    };
+  }
+
+  getParallelGroup(groupId) {
+    return this.parallelGroupMap[groupId] || null;
+  }
+
+  getParallelGroups() {
+    return Object.values(this.parallelGroupMap);
+  }
+
+  shouldExecutePhase(phase, context = {}) {
+    if (phase.conditional && !evaluateCondition(phase.conditional, context)) return false;
+    if (phase.skip_if_exists && context.fileExists) {
+      const fp = path.join(context.featureDir || '', phase.skip_if_exists);
+      if (context.fileExists(fp)) {
+        this.logger.info(`[ORCHESTRATOR] Skip ${phase.id} (${phase.display_name}) - artifact exists`);
+        return false;
+      }
+    }
+    return true;
+  }
+
+  getParallelSchedulingConfig() {
+    return this.config.parallel_scheduling || {
+      max_concurrent_tasks: 2, fallback_to_serial_on_failure: true, fallback_reason_log: true,
+    };
+  }
+
+  getSummary() {
+    return {
+      mode: this.mode, isFallback: this.isFallback,
+      phasesCount: Object.keys(this.phaseMap).length,
+      gatesCount: Object.keys(this.gateBehaviorMap).length,
+      parallelGroupsCount: Object.keys(this.parallelGroupMap).length,
+      version: this.config.version,
+    };
+  }
+}
+
+/**
+ * 验证 orchestration.yaml 配置（向后兼容薄壳，T-011）
+ *
+ * 历史逻辑：手写循环校验 modes/phases/gates（已移除）。
+ * 当前实现：保留向后兼容的 null 检查和 modes 存在性检查，
+ * 内部核心校验已迁移至 loadAndValidateConfig() 使用 orchestrationBaseSchema.safeParse()。
+ *
+ * 本函数作为公共 API 保留，仅做基础 null/modes 检查，
+ * 调用方应优先使用 orchestrationBaseSchema.safeParse() 获取完整 Zod 校验。
+ */
+export function validateOrchestrationYaml(config) {
+  const errors = [];
+  const warnings = [];
+
+  // 基础 null 检查
+  if (!config) {
+    errors.push('Config is null or undefined');
+    return { valid: false, errors, warnings };
+  }
+
+  // modes 存在性检查（最关键的结构约束）
+  if (!config.modes || Object.keys(config.modes).length === 0) {
+    errors.push('modes section is missing or empty');
+  }
+
+  // 语义警告（向后兼容）
+  if (config.modes && !config.modes.feature) {
+    warnings.push('feature mode not found');
+  }
+  if (!config.gates || Object.keys(config.gates).length === 0) {
+    warnings.push('No gates defined');
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * 安全的条件表达式求值（不使用 eval）
+ */
+export function evaluateCondition(condition, context = {}) {
+  if (!condition) return true;
+
+  try {
+    // "variable in [val1, val2]"
+    const inMatch = condition.match(/^(\w+)\s+in\s+\[(.*)\]$/);
+    if (inMatch) {
+      const values = inMatch[2].split(',').map((s) => s.trim().replace(/['"]/g, ''));
+      return context[inMatch[1]] !== undefined && values.includes(String(context[inMatch[1]]));
+    }
+
+    // "variable == value"
+    const eqMatch = condition.match(/^(\w+)\s*==\s*(.+)$/);
+    if (eqMatch) return String(context[eqMatch[1]]) === eqMatch[2].trim().replace(/['"]/g, '');
+
+    // "variable != value"
+    const neqMatch = condition.match(/^(\w+)\s*!=\s*(.+)$/);
+    if (neqMatch) return String(context[neqMatch[1]]) !== neqMatch[2].trim().replace(/['"]/g, '');
+
+    // "variable > number"
+    const gtMatch = condition.match(/^(\w+)\s*>\s*(\d+)$/);
+    if (gtMatch) { const v = Number(context[gtMatch[1]]); return !isNaN(v) && v > parseInt(gtMatch[2], 10); }
+
+    console.warn(`[ORCHESTRATOR] 无法解析条件: "${condition}"`);
+    return true;
+  } catch { return true; }
+}
+
+function getDefaultBehaviorForPolicy(policy, gateId) {
+  if (policy === 'strict') return 'always';
+  if (policy === 'autonomous') return 'on_failure';
+  const balanced = {
+    GATE_RESEARCH: 'auto', GATE_DESIGN: 'always', GATE_ANALYSIS: 'on_failure',
+    GATE_TASKS: 'always', GATE_IMPLEMENT_MID: 'on_failure', GATE_VERIFY: 'always',
+  };
+  return balanced[gateId] || null;
+}
+
+const defaultLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+  error: (m) => console.error(m),
+  debug: () => {},
+};

package/plugins/spec-driver/scorecards/default-governance.yaml

@@ -0,0 +1,63 @@
+schemaVersion: 1
+ruleset:
+  id: "default-governance"
+  title: "默认持续治理评分"
+  description: "基于 current-spec、verification、quality-report、Catalog 与 workflow registry 的最小持续治理评分。"
+rules:
+  - id: "spec-freshness"
+    title: "Current Spec 新鲜度"
+    evaluator: "spec-freshness"
+    weight: 20
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"
+    thresholds:
+      warnLagDays: 7
+      failLagDays: 30
+      maxLaggingSpecsWarn: 2
+  - id: "verification-freshness"
+    title: "Verification 新鲜度"
+    evaluator: "verification-freshness"
+    weight: 20
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"
+    thresholds:
+      warnCoverageRatio: 0.8
+  - id: "docs-coverage"
+    title: "文档覆盖率"
+    evaluator: "docs-coverage"
+    weight: 20
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"
+    thresholds:
+      passCoverageRatio: 1
+      warnCoverageRatio: 0.75
+  - id: "docs-conflicts"
+    title: "文档冲突"
+    evaluator: "docs-conflicts"
+    weight: 15
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"
+  - id: "branch-hygiene"
+    title: "分支规范卫生"
+    evaluator: "branch-hygiene"
+    weight: 10
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"
+  - id: "workflow-readiness"
+    title: "Workflow 就绪度"
+    evaluator: "workflow-readiness"
+    weight: 15
+    appliesTo:
+      kinds:
+        - "library-tooling"
+        - "plugin"

package/plugins/spec-driver/scripts/codex-skills.sh

@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Spec Driver Codex skills 安装/卸载脚本（独立入口）
+
+set -euo pipefail
+
+MODE="project"
+ACTION="install"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+usage() {
+  cat <<'USAGE'
+用法:
+  bash "\$PLUGIN_DIR/scripts/codex-skills.sh" install [--global]
+  bash "\$PLUGIN_DIR/scripts/codex-skills.sh" remove [--global]
+
+说明:
+  install   安装 Spec Driver 的 Codex 包装技能到 .codex/skills
+  remove    移除已安装的 Spec Driver Codex 包装技能
+  --global  目标目录改为 ~/.codex/skills
+
+环境变量:
+  CODEX_SKILL_PROJECT_ROOT  覆盖 project 模式的目标项目根目录
+USAGE
+}
+
+for arg in "$@"; do
+  case "$arg" in
+    install|remove)
+      ACTION="$arg"
+      ;;
+    --global|-g)
+      MODE="global"
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[错误] 未知参数: $arg" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ "$MODE" == "global" ]]; then
+  TARGET_DIR="$HOME/.codex/skills"
+else
+  if [[ -n "${CODEX_SKILL_PROJECT_ROOT:-}" ]]; then
+    PROJECT_ROOT="$CODEX_SKILL_PROJECT_ROOT"
+  elif git -C "$PWD" rev-parse --show-toplevel >/dev/null 2>&1; then
+    PROJECT_ROOT="$(git -C "$PWD" rev-parse --show-toplevel)"
+  else
+    PROJECT_ROOT="$PWD"
+  fi
+  TARGET_DIR="$PROJECT_ROOT/.codex/skills"
+fi
+
+SKILLS=(
+  "spec-driver-constitution"
+  "spec-driver-feature"
+  "spec-driver-implement"
+  "spec-driver-story"
+  "spec-driver-fix"
+  "spec-driver-resume"
+  "spec-driver-sync"
+  "spec-driver-doc"
+)
+
+ensure_source_exists() {
+  local source_skill_path="$1"
+  if [[ ! -f "$source_skill_path" ]]; then
+    echo "[错误] 找不到 source skill: $source_skill_path" >&2
+    exit 1
+  fi
+}
+
+rewrite_codex_runtime_text() {
+  sed \
+    -e 's|/spec-driver:spec-driver-feature|$spec-driver-feature|g' \
+    -e 's|/spec-driver:spec-driver-implement|$spec-driver-implement|g' \
+    -e 's|/spec-driver:spec-driver-story|$spec-driver-story|g' \
+    -e 's|/spec-driver:spec-driver-fix|$spec-driver-fix|g' \
+    -e 's|/spec-driver:spec-driver-resume|$spec-driver-resume|g' \
+    -e 's|/spec-driver:spec-driver-sync|$spec-driver-sync|g' \
+    -e 's|/spec-driver:spec-driver-doc|$spec-driver-doc|g' \
+    -e 's|Claude Code 的 Task tool|Task tool（Codex 下按内联子代理执行）|g' \
+    -e 's|在同一消息中同时发出多个 Task tool 调用。Claude Code 的 function calling 机制支持在单个 assistant 消息中发出多个 tool calls，这些 tool calls 会被并行执行。|若当前环境支持并行工具调用，则在同一消息中并行执行；否则按本 Skill 的回退规则串行执行。|g'
+}
+
+write_frontmatter() {
+  local skill_name="$1"
+  local source_skill_path="$2"
+
+  awk -v skill_name="$skill_name" '
+    NR == 1 && $0 == "---" {
+      in_frontmatter = 1
+      print
+      next
+    }
+    in_frontmatter {
+      if ($0 ~ /^name:[[:space:]]/) {
+        print "name: " skill_name
+        next
+      }
+      print
+      if ($0 == "---") {
+        exit
+      }
+    }
+  ' "$source_skill_path"
+}
+
+write_codex_adapter() {
+  local skill_name="$1"
+  local source_skill_name="$2"
+  local source_command="/spec-driver:$source_skill_name"
+
+  cat <<EOF_ADAPTER
+## Codex Runtime Adapter
+
+此 Skill 在安装时直接同步自 \`\$PLUGIN_DIR/skills/$source_skill_name/SKILL.md\` 的描述与正文，只额外叠加以下 Codex 运行时差异：
+
+- 命令别名：正文中的 \`$source_command\` 在 Codex 中等价于 \`\$$skill_name\`
+- 子代理执行：正文中的 \`Task(...)\` / \`Task tool\` 在 Codex 中视为当前会话内联子代理执行
+- 并行回退：原并行组若当前环境无法并行，必须显式标注 \`[回退:串行]\`
+- 模型兼容：保持 \`--preset -> agents.{agent_id}.model(仅显式配置时生效) -> preset 默认\` 优先级；runtime=codex 时先做 \`model_compat\` 归一化，不可用时标注 \`[模型回退]\`
+- 质量门与产物：所有质量门、制品路径、写入边界与 source skill 完全一致，不得弱化或越界
+
+---
+EOF_ADAPTER
+}
+
+write_wrapper_source_contract() {
+  local source_skill_name="$1"
+
+  cat <<EOF_CONTRACT
+## Wrapper Source Contract
+
+- Canonical source: \`\$PLUGIN_DIR/skills/$source_skill_name/SKILL.md\`
+- Generated by: \`bash \$PLUGIN_DIR/scripts/codex-skills.sh install\`
+- Contract: \`\$PLUGIN_DIR/contracts/wrapper-source-of-truth.yaml\`
+- Maintenance rule: edit the source skill, then reinstall; do not edit this wrapper directly
+
+---
+EOF_CONTRACT
+}
+
+write_skill_body() {
+  local source_skill_path="$1"
+
+  awk '
+    NR == 1 && $0 == "---" {
+      in_frontmatter = 1
+      next
+    }
+    in_frontmatter {
+      if ($0 == "---") {
+        in_frontmatter = 0
+      }
+      next
+    }
+    {
+      print
+    }
+  ' "$source_skill_path" | rewrite_codex_runtime_text
+}
+
+write_wrapper() {
+  local skill_name="$1"
+  local source_skill_name="$2"
+  local source_skill_path="$PLUGIN_DIR/skills/$source_skill_name/SKILL.md"
+  local target_file="$TARGET_DIR/$skill_name/SKILL.md"
+
+  ensure_source_exists "$source_skill_path"
+  mkdir -p "$(dirname "$target_file")"
+
+  {
+    write_frontmatter "$skill_name" "$source_skill_path"
+    printf '\n'
+    write_wrapper_source_contract "$source_skill_name"
+    printf '\n'
+    write_codex_adapter "$skill_name" "$source_skill_name"
+    printf '\n'
+    write_skill_body "$source_skill_path"
+  } > "$target_file"
+}
+
+install_all() {
+  write_wrapper "spec-driver-constitution" "spec-driver-constitution"
+  write_wrapper "spec-driver-feature" "spec-driver-feature"
+  write_wrapper "spec-driver-implement" "spec-driver-implement"
+  write_wrapper "spec-driver-story" "spec-driver-story"
+  write_wrapper "spec-driver-fix" "spec-driver-fix"
+  write_wrapper "spec-driver-resume" "spec-driver-resume"
+  write_wrapper "spec-driver-sync" "spec-driver-sync"
+  write_wrapper "spec-driver-doc" "spec-driver-doc"
+
+  echo "Spec Driver Codex skills 安装完成: $TARGET_DIR"
+}
+
+remove_all() {
+  local removed=0
+  for skill in "${SKILLS[@]}"; do
+    local dir="$TARGET_DIR/$skill"
+    if [[ -d "$dir" ]]; then
+      rm -rf "$dir"
+      echo "✓ 已删除: $dir"
+      removed=$((removed + 1))
+    fi
+  done
+
+  if [[ $removed -eq 0 ]]; then
+    echo "未检测到已安装的 Spec Driver Codex skills，无需清理"
+  else
+    echo "Spec Driver Codex skills 已移除: $removed 个"
+  fi
+}
+
+if [[ "$ACTION" == "install" ]]; then
+  install_all
+else
+  remove_all
+fi

package/plugins/spec-driver/scripts/experimental/README.md

@@ -0,0 +1,9 @@
+# 实验性脚本
+
+以下脚本属于实验性治理功能，尚无明确消费者。不在 `repo:sync` 主链路执行。
+
+- `plugins/spec-driver/scripts/generate-product-scorecards.mjs` — 记分卡生成
+- `plugins/spec-driver/scripts/generate-adoption-insights.mjs` — 采纳情况报告
+- `plugins/spec-driver/scripts/generate-workflow-registry.mjs` — Workflow 注册表
+
+待这些功能有明确的消费场景（如 CI Dashboard、README Badge）后再纳入主链路。