spectra-cli 4.1.1

package/plugins/spec-driver/contracts/orchestration-overrides-contract.yaml

@@ -0,0 +1,124 @@
+# orchestration-overrides-contract.yaml
+# spec-driver 项目级流程定制（Per-Project Workflow Overrides）合同
+# 说明 .specify/orchestration-overrides.yaml 的 schema、合并语义与降级策略
+#
+# 参考风格：plugins/spec-driver/contracts/wrapper-source-of-truth.yaml
+
+contract: orchestration-overrides
+version: "1.0"
+description: >
+  spec-driver 项目级流程定制（Per-Project Workflow Overrides）合同：
+  定义 .specify/orchestration-overrides.yaml 的 schema、合并语义、降级策略。
+  plugin base 的 orchestration.yaml 为底层默认值，项目层仅声明差异覆盖。
+
+canonical_schema: "plugins/spec-driver/contracts/orchestration-schema.mjs"
+
+vs_spec_driver_config:
+  description: >
+    orchestration-overrides.yaml 与 spec-driver.config.yaml 职责分工说明
+  orchestration_overrides:
+    - "流程结构覆盖：mode phase 序列、gate behavior、parallel_scheduling"
+    - "作用：控制编排引擎如何执行 phases/gates"
+  spec_driver_config:
+    - "行为偏好：gate_policy、resume_strategy、research.enabled 等"
+    - "作用：控制 agent 在执行时的决策偏好（非结构覆盖）"
+  rule: "流程结构覆盖放 orchestration-overrides.yaml；行为偏好放 spec-driver.config.yaml"
+
+supported_overrides:
+  - path: "modes.<mode>"
+    semantic: "整段替换"
+    constraint: "mode key 必须是 base reserved enum: feature|story|implement|fix|resume|sync|doc|refactor"
+    notes: >
+      overrides 中出现同名 mode 时，整段 phases 数组替换 base 对应 mode；
+      base 的其余 phase 字段不保留。无法局部 patch 单个 phase，需完整声明 phases 数组。
+    reserved_modes:
+      - feature
+      - story
+      - implement
+      - fix
+      - resume
+      - sync
+      - doc
+      - refactor
+
+  - path: "gates.<GATE_ID>"
+    semantic: "对象字段合并"
+    constraint: "仅 default_behavior / severity / hard_gate_modes 三个字段可覆盖"
+    notes: >
+      未在 overrides 中声明的 gate 字段继承 base 值。
+      hard_gate_modes 数组是整段替换（非追加）。
+    valid_values:
+      default_behavior:
+        - value: always
+          desc: 总是触发 gate 检查点（用户确认）
+        - value: auto
+          desc: 根据条件自动决定是否触发
+        - value: on_failure
+          desc: 仅在工具链或质量检查失败时触发
+        - value: skip
+          desc: 跳过该 gate 检查点（CI 或自动化场景）
+
+  - path: "parallel_scheduling.*"
+    semantic: "顶层标量后者覆盖前者（scalar override）"
+    notes: >
+      仅支持顶层标量字段（如 max_concurrent_tasks）。
+      CI 资源受限时可将 max_concurrent_tasks 降为 1（串行执行）。
+
+out_of_scope:
+  - id: phase_patch
+    description: "二期；按 phase id 局部 patch 单个 phase 字段"
+  - id: mode_extends
+    description: "二期；schema 接受 modes.<m>.extends 字段但 MVP resolver 不处理，仍整段替换"
+  - id: parallel_groups
+    description: "二期；overrides 中出现 parallel_groups 时 strip 该字段 + 发出 unsupported-field warning，其余合法字段照常生效"
+
+diagnostic_codes:
+  - code: orchestration-overrides.parse-error
+    level: warning
+    trigger: ".specify/orchestration-overrides.yaml YAML 语法错误（parseYamlDocument 抛出异常）"
+    behavior: "忽略 overrides，回退使用 base config"
+
+  - code: orchestration-overrides.schema-fallback
+    level: warning
+    trigger: "Zod schema 校验失败（含非 reserved mode 名、必填字段缺失等）"
+    behavior: "忽略 overrides，回退使用 base config"
+
+  - code: orchestration-overrides.version-mismatch
+    level: warning
+    trigger: "overrides.version 与 base.version 不一致（resolver 层额外比对，非 Zod 层）"
+    behavior: "忽略 overrides，回退使用 base config（专属 code，不复用 schema-fallback）"
+
+  - code: orchestration-overrides.unsupported-field
+    level: warning
+    trigger: "overrides 含 MVP 不支持但二期保留的字段（如 parallel_groups）"
+    behavior: "strip 该字段后继续处理其余合法字段，不使整体 overrides 失效"
+
+  - code: orchestration-overrides.mode-overridden
+    level: info
+    trigger: "overrides 中 mode 名与 base 重名，整段替换已生效"
+    behavior: "提示 mode 被 overrides 整段替换（informational，仍生效）"
+
+  - code: orchestration.base-invalid
+    level: error
+    trigger: "base orchestration.yaml 无法通过 orchestrationBaseSchema Zod 校验（base 本身损坏）"
+    behavior: "使用 generateFallbackConfig() 内置后备配置，不再尝试合并 overrides"
+
+cli:
+  command: >
+    node plugins/spec-driver/scripts/orchestrator-cli.mjs
+    effective-orchestration <mode>
+    [--annotate|--diff]
+    [--format yaml|json]
+    [--project-root <path>]
+  examples:
+    - "node plugins/spec-driver/scripts/orchestrator-cli.mjs effective-orchestration fix --annotate"
+    - "node plugins/spec-driver/scripts/orchestrator-cli.mjs effective-orchestration feature --format json"
+    - "node plugins/spec-driver/scripts/orchestrator-cli.mjs effective-orchestration fix --diff"
+
+examples_path: "plugins/spec-driver/templates/orchestration-overrides.example.yaml"
+
+notes:
+  - "overrides 文件不存在时静默使用 base config，不输出任何 diagnostic（正常场景）"
+  - "overrides 文件存在但为空（零字节）时等效于无 overrides，静默使用 base"
+  - "YAML anchor（& / <<:）不被 simple-yaml.mjs 支持；若 anchor 导致解析异常则触发 parse-error 降级"
+  - "simple-yaml.mjs 不提供行号信息，diagnostic 无法精确指向出错行"

package/plugins/spec-driver/contracts/orchestration-schema.mjs

@@ -0,0 +1,301 @@
+/**
+ * orchestration-schema.mjs
+ * Feature 133 — orchestration 配置的 Zod 三件套 Schema 定义
+ *
+ * 导出：
+ *   - phaseSchema                  Phase 定义 Schema（base 用）
+ *   - gateDefinitionSchema         Gate 定义 Schema（base 用）
+ *   - gateOverrideSchema           Gate 覆盖 Schema（overrides 用）
+ *   - modeDefinitionSchema         Mode 定义 Schema（base 用）
+ *   - modeOverrideSchema           Mode 覆盖 Schema（overrides 用）
+ *   - parallelGroupSchema          并行组 Schema（base 用）
+ *   - parallelSchedulingSchema     全局并行调度 Schema
+ *   - orchestrationBaseSchema      校验 plugin base orchestration.yaml
+ *   - orchestrationOverridesSchema 校验项目级 overrides 文件
+ *   - orchestrationMergedSchema    校验合并后的 config（复用 base schema）
+ *   - formatZodIssue               Zod issue 中文化格式辅助函数
+ */
+
+import { z } from 'zod';
+
+// ─────────────────────────────────────────────────────────────
+// Zod issue 中文化格式辅助
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * 将 Zod issue 格式化为中文可读的错误信息
+ * @param {import('zod').ZodIssue} issue
+ * @returns {string}
+ */
+export function formatZodIssue(issue) {
+  const path = issue.path.length > 0 ? `字段 "${issue.path.join('.')}"` : '配置根';
+  switch (issue.code) {
+    case 'invalid_type':
+      return `${path}：类型错误，期望 ${issue.expected}，实际为 ${issue.received}`;
+    case 'invalid_enum_value':
+      return `${path}：不合法的枚举值 "${issue.received}"，合法值为 [${issue.options?.join(' | ')}]`;
+    case 'unrecognized_keys':
+      return `${path}：包含未识别的字段 [${issue.keys?.join(', ')}]`;
+    case 'too_small':
+      return `${path}：值过小，最小值为 ${issue.minimum}`;
+    case 'too_big':
+      return `${path}：值过大，最大值为 ${issue.maximum}`;
+    case 'invalid_string':
+      return `${path}：字符串格式不合法`;
+    default:
+      return `${path}：${issue.message}`;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// 共用子 Schema 基础类型（从 orchestration.yaml 实际结构推导）
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Phase 定义 Schema（base orchestration.yaml 中 phases 数组元素）
+ *
+ * 关键观察（来自 orchestration.yaml 实际字段）：
+ *   - agent: null | string | string[]（三种形态）
+ *   - agent_mode: inline | single | parallel_group | gate | orchestrator_verify | batch_loop
+ *   - gates_before / gates_after: null | string[]（nullable，非 optional）
+ *   - conditional / skip_if_exists: null | string（nullable）
+ *   - is_critical: boolean
+ */
+export const phaseSchema = z.object({
+  id: z.string({ required_error: 'phase id 为必填字段' }),
+  name: z.string({ required_error: 'phase name 为必填字段' }),
+  display_name: z.string({ required_error: 'phase display_name 为必填字段' }),
+  // agent 可以是 null、string 或 string 数组（parallel_group 模式时）
+  agent: z.union([
+    z.null(),
+    z.string(),
+    z.array(z.string()),
+  ]),
+  // agent_mode 枚举——来自 orchestration.yaml 实际值
+  agent_mode: z.enum([
+    'inline',
+    'single',
+    'parallel_group',
+    'gate',
+    'orchestrator_verify',
+    'batch_loop',
+  ], {
+    error_map: (issue) => {
+      if (issue.code === 'invalid_enum_value') {
+        return {
+          message: `agent_mode 不合法：期望 [inline|single|parallel_group|gate|orchestrator_verify|batch_loop]，实际为 "${issue.received}"`,
+        };
+      }
+      return { message: issue.message };
+    },
+  }),
+  // gates_before / gates_after：null 或 string 数组（YAML 中的 null 必须用 .nullable()）
+  gates_before: z.array(z.string()).nullable(),
+  gates_after: z.array(z.string()).nullable(),
+  // conditional / skip_if_exists：null 或字符串表达式
+  conditional: z.string().nullable(),
+  skip_if_exists: z.string().nullable(),
+  is_critical: z.boolean(),
+});
+
+/**
+ * Gate 定义 Schema（base orchestration.yaml 中 gates 块）
+ *
+ * 关键观察：
+ *   - type: string（自由文本，如 "research_checkpoint"）
+ *   - applicable_modes: string[] 或不存在（非所有 gate 都有此字段）
+ *   - default_behavior: "always" | "auto" | "on_failure" | "skip"（skip 表示跳过该 gate 检查点）
+ *   - severity: "critical" | "non_critical"（实际值，非 spec 定义的 warning/info）
+ *   - hard_gate_modes: null | string[]（nullable）
+ *   - insertion_point: null | string（nullable）
+ */
+export const gateDefinitionSchema = z.object({
+  type: z.string(),
+  // applicable_modes 在某些 gate 中存在（如 GATE_RESEARCH），某些不存在（如 GATE_VERIFY 有）
+  // 实际上所有 gate 都有此字段，但为了健壮性设为 optional
+  applicable_modes: z.array(z.string()).optional(),
+  description: z.string(),
+  // 实际 default_behavior 值包含 on_failure 和 skip（override 场景允许 skip 跳过 gate）
+  default_behavior: z.enum(['always', 'auto', 'on_failure', 'skip'], {
+    error_map: (issue) => {
+      if (issue.code === 'invalid_enum_value') {
+        return {
+          message: `default_behavior 不合法：期望 [always | auto | on_failure | skip]，实际为 "${issue.received}"`,
+        };
+      }
+      return { message: issue.message };
+    },
+  }),
+  // 实际 severity 值为 "critical" 和 "non_critical"（非 spec 文档定义的 warning/info）
+  severity: z.enum(['critical', 'non_critical', 'warning', 'info'], {
+    error_map: (issue) => {
+      if (issue.code === 'invalid_enum_value') {
+        return {
+          message: `severity 不合法：期望 [critical | non_critical | warning | info]，实际为 "${issue.received}"`,
+        };
+      }
+      return { message: issue.message };
+    },
+  }),
+  // hard_gate_modes：YAML 中显式为 null（必须用 .nullable()，不能用 .optional()）
+  hard_gate_modes: z.array(z.string()).nullable(),
+  // insertion_point：YAML 中显式为 null 或字符串
+  insertion_point: z.string().nullable(),
+});
+
+/**
+ * Gate 覆盖 Schema（overrides 文件中 gates 块，仅允许部分字段）
+ * 只有 default_behavior / severity / hard_gate_modes 可被覆盖
+ */
+export const gateOverrideSchema = z.object({
+  // overrides 中的 default_behavior 允许 always/auto/on_failure/skip（与 gateDefinitionSchema 对齐）
+  default_behavior: z.enum(['always', 'auto', 'on_failure', 'skip']).optional(),
+  severity: z.enum(['critical', 'non_critical', 'warning', 'info']).optional(),
+  // hard_gate_modes 整段替换，非追加
+  hard_gate_modes: z.array(z.string()).optional(),
+}).strict();
+
+/**
+ * Mode 定义 Schema（base orchestration.yaml 中 modes 块）
+ */
+export const modeDefinitionSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  phases: z.array(phaseSchema).min(1, { message: 'phases 数组不能为空' }),
+});
+
+/**
+ * Mode 覆盖 Schema（overrides 文件中 modes 块，整段替换语义）
+ * 整段替换要求用户提供完整的 mode 定义（name/description/phases）
+ * extends 字段为 MVP 预留：schema 接受但 resolver 不处理
+ */
+export const modeOverrideSchema = z.object({
+  name: z.string().optional(),         // 与 modeDefinitionSchema 保持一致（整段替换时合并进 mergedModes）
+  description: z.string().optional(),  // 同上
+  extends: z.string().optional(),      // 二期预留，MVP 接受但不处理
+  // phases 的 agent_mode 在 override 场景下也接受额外值，或直接复用 phaseSchema
+  phases: z.array(phaseSchema).min(0),
+}).strip();  // strip 未知字段（与整体 .strict() 策略一致；二期新增字段时在此处显式声明）
+
+/**
+ * 并行组 Schema（base orchestration.yaml 中 parallel_groups 块）
+ */
+export const parallelGroupSchema = z.object({
+  members: z.array(z.string()),
+  convergence_point: z.string(),
+  fallback_strategy: z.string(),
+  max_concurrent: z.number().int().positive(),
+  description: z.string(),
+});
+
+/**
+ * 全局并行调度 Schema（base orchestration.yaml 中 parallel_scheduling 块）
+ */
+export const parallelSchedulingSchema = z.object({
+  max_concurrent_tasks: z.number().int().positive(),
+  fallback_to_serial_on_failure: z.boolean(),
+  fallback_reason_log: z.boolean(),
+});
+
+// ─────────────────────────────────────────────────────────────
+// Base reserved mode names（FR-007-A，CL-001）
+// ─────────────────────────────────────────────────────────────
+
+/** Base 保留 mode 名称列表（overrides schema 中做 enum 校验）*/
+export const BASE_RESERVED_MODE_NAMES = [
+  'feature',
+  'story',
+  'implement',
+  'fix',
+  'resume',
+  'sync',
+  'doc',
+  'refactor',
+];
+
+// ─────────────────────────────────────────────────────────────
+// 三件套 Schema
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * orchestrationBaseSchema — 校验 plugin base orchestration.yaml
+ *
+ * 设计原则（FR-024 / R11）：先以现有 orchestration.yaml 内容为准定义 schema，
+ * 确保现有文件 100% 通过 Zod 校验，再扩展为 overrides 使用。
+ *
+ * 字段清单（来自 orchestration.yaml 实际结构）：
+ *   - version: string，必填
+ *   - parallel_scheduling: 并行调度配置
+ *   - gates: Record<GATE_ID, GateDefinition>
+ *   - parallel_groups: Record<GROUP_ID, ParallelGroup>
+ *   - modes: Record<ModeName, ModeDefinition>（所有 8 个模式）
+ */
+export const orchestrationBaseSchema = z.object({
+  version: z.string({ required_error: 'version 为必填字段' }),
+  parallel_scheduling: parallelSchedulingSchema,
+  gates: z.record(z.string(), gateDefinitionSchema),
+  parallel_groups: z.record(z.string(), parallelGroupSchema),
+  modes: z.record(z.string(), modeDefinitionSchema),
+});
+
+/**
+ * orchestrationOverridesSchema — 校验项目级 .specify/orchestration-overrides.yaml
+ *
+ * 关键设计决策（GATE_DESIGN CL-001/010）：
+ *   - version 必填（CL-008，resolver 比对 base version）
+ *   - modes key 使用显式 z.object() 列出 8 个 mode（CL-001 enum 校验）
+ *   - parallel_groups 字段：schema 接受但 transform 时 strip，发出 unsupported-field warning
+ *   - $schema_version 和 modes.<m>.extends 字段：接受但 resolver 不特殊处理（FR-014）
+ *
+ * 注意：parallel_groups 由 resolver 步骤 6 手动检测并 strip；schema 层仅声明该字段以免被 .strict() 拒绝
+ */
+export const orchestrationOverridesSchema = z.object({
+  // 二期预留字段：schema 接受但 MVP resolver 不处理（FR-014）
+  $schema_version: z.string().optional(),
+
+  // version 必填（CL-008）——resolver 层做 base/overrides version 比对
+  version: z.string({ required_error: 'overrides 文件必须包含 version 字段' }),
+
+  // modes key 使用显式枚举——拒绝非 reserved name（CL-001，FR-007-A）
+  // 非 reserved 名 → safeParse 返回 error → 触发 schema-fallback → 整体 overrides 降级到 base
+  // 使用 .strict() 拒绝任何不在 8 个 reserved name 中的 mode key
+  modes: z.object({
+    feature: modeOverrideSchema.optional(),
+    story: modeOverrideSchema.optional(),
+    implement: modeOverrideSchema.optional(),
+    fix: modeOverrideSchema.optional(),
+    resume: modeOverrideSchema.optional(),
+    sync: modeOverrideSchema.optional(),
+    doc: modeOverrideSchema.optional(),
+    refactor: modeOverrideSchema.optional(),
+  }).strict({
+    message: 'modes 字段包含非法的 mode 名称，合法值为 [feature|story|implement|fix|resume|sync|doc|refactor]',
+  }).optional(),
+
+  // gates 字段：Record<GATE_ID, GateOverride>，对象级字段合并
+  gates: z.record(z.string(), gateOverrideSchema).optional(),
+
+  // parallel_scheduling：标量覆盖
+  parallel_scheduling: z.object({
+    max_concurrent_tasks: z.number().int().positive().optional(),
+    fallback_to_serial_on_failure: z.boolean().optional(),
+    fallback_reason_log: z.boolean().optional(),
+  }).optional(),
+
+  // parallel_groups：MVP 不支持覆盖，schema 接受但 resolver 层 strip + warning
+  // 不 reject 整个 overrides，其余合法字段照常生效（CL-010，FR-022）
+  // 使用 z.record() 保留类型信息，同时接受任意结构；由 resolver 在 parse 前检测并 strip
+  parallel_groups: z.record(z.string(), z.unknown()).optional(),
+}).strict({
+  // 顶层真正未知字段使用 .strict() 策略拒绝（NFR-003）
+  // 注意：parallel_groups 已显式声明，不会被 .strict() 拒绝
+  message: 'overrides 文件包含未识别的顶层字段，请检查字段名称',
+});
+
+/**
+ * orchestrationMergedSchema — 校验合并后的 config
+ *
+ * 合并结果必须满足 base schema 的全部约束（FR-013）
+ * 复用 orchestrationBaseSchema 实现 DRY 原则（NFR-006）
+ */
+export const orchestrationMergedSchema = orchestrationBaseSchema;

package/plugins/spec-driver/contracts/scan-project-output.md

@@ -0,0 +1,70 @@
+# scan-project.sh 输出契约
+
+**文件**: `plugins/spec-driver/scripts/scan-project.sh`  
+**输出模式**: `bash "$PLUGIN_DIR/scripts/scan-project.sh" --json`
+
+本文档定义 `scan-project.sh` 的 JSON 输出字段，供 `spec-driver-doc` 和后续模板 / agent / skill 引用。新增字段应保持向后兼容；删除或重命名字段属于破坏性变更。
+
+## 顶层字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 项目名称；优先来自项目配置文件，缺失时回退目录名 |
+| `version` | string \| null | 版本号 |
+| `description` | string \| null | 项目描述 |
+| `license` | string \| null | 已声明的协议 |
+| `author` | object \| null | 作者信息；格式见下方 |
+| `scripts` | object | npm / 项目脚本映射；非 Node 项目可为空对象 |
+| `dependencies` | object | 运行时依赖映射 |
+| `devDependencies` | object | 开发依赖映射 |
+| `repository` | string \| object \| null | 仓库地址或仓库对象；当前消费侧应兼容 `null` |
+| `main` | string \| null | 主入口 |
+| `bin` | string \| object \| null | CLI 入口 |
+| `git` | object | git 元信息；格式见下方 |
+| `directoryTree` | string | 顶层目录树快照，供 README / 项目结构章节使用 |
+| `projectType` | string | `cli` / `library` / `web-app` / `rust` / `go` / `python-lib` / `python-app` / `java` / `node` / `unknown` |
+| `ecosystem` | string | `node` / `python` / `rust` / `go` / `java` / `unknown` |
+| `existingFiles` | object | 目标文档文件存在性映射 |
+| `hasPackageJson` | boolean | 是否检测到 `package.json` |
+| `hasGitRepo` | boolean | 是否检测到 git 仓库 |
+| `missingFields` | string[] | 未提取到的字段列表，供生成完成报告提示 |
+
+## 子对象
+
+### `author`
+
+```json
+{
+  "name": "string | null",
+  "email": "string | null"
+}
+```
+
+### `git`
+
+```json
+{
+  "userName": "string | null",
+  "userEmail": "string | null",
+  "remoteUrl": "string | null",
+  "defaultBranch": "string"
+}
+```
+
+### `existingFiles`
+
+```json
+{
+  "README.md": true,
+  "LICENSE": false,
+  "CONTRIBUTING.md": false,
+  "CODE_OF_CONDUCT.md": false
+}
+```
+
+## 使用规则
+
+1. `spec-driver-doc` 将此输出视为**分发元信息层**，而不是产品语义层。
+2. 当项目存在 `specs/products/*/current-spec.md` 时，README 的产品定位、核心价值、主要工作流应优先来自 `current-spec.md`，而不是本契约中的 `description`。
+3. 当字段缺失时，消费方必须使用 `[待补充]` 或降级逻辑，而不是假设该字段存在。
+4. 若后续需要新增字段，应在此文档追加说明，并保持旧字段兼容。

package/plugins/spec-driver/contracts/wrapper-source-of-truth.yaml

@@ -0,0 +1,44 @@
+schemaVersion: 1
+plugin:
+  id: "spec-driver"
+  sourceRoot: "plugins/spec-driver"
+  metadataSource: "plugins/spec-driver/.claude-plugin/plugin.json"
+  marketplaceManifest: ".claude-plugin/marketplace.json"
+
+codexWrappers:
+  sourceRoot: "plugins/spec-driver/skills"
+  targetRoot: ".codex/skills"
+  generator:
+    script: "plugins/spec-driver/scripts/codex-skills.sh"
+    command: "npm run codex:spec-driver:install"
+  entries:
+    - id: "spec-driver-constitution"
+      source: "plugins/spec-driver/skills/spec-driver-constitution/SKILL.md"
+      target: ".codex/skills/spec-driver-constitution/SKILL.md"
+    - id: "spec-driver-feature"
+      source: "plugins/spec-driver/skills/spec-driver-feature/SKILL.md"
+      target: ".codex/skills/spec-driver-feature/SKILL.md"
+    - id: "spec-driver-implement"
+      source: "plugins/spec-driver/skills/spec-driver-implement/SKILL.md"
+      target: ".codex/skills/spec-driver-implement/SKILL.md"
+    - id: "spec-driver-story"
+      source: "plugins/spec-driver/skills/spec-driver-story/SKILL.md"
+      target: ".codex/skills/spec-driver-story/SKILL.md"
+    - id: "spec-driver-fix"
+      source: "plugins/spec-driver/skills/spec-driver-fix/SKILL.md"
+      target: ".codex/skills/spec-driver-fix/SKILL.md"
+    - id: "spec-driver-resume"
+      source: "plugins/spec-driver/skills/spec-driver-resume/SKILL.md"
+      target: ".codex/skills/spec-driver-resume/SKILL.md"
+    - id: "spec-driver-sync"
+      source: "plugins/spec-driver/skills/spec-driver-sync/SKILL.md"
+      target: ".codex/skills/spec-driver-sync/SKILL.md"
+    - id: "spec-driver-doc"
+      source: "plugins/spec-driver/skills/spec-driver-doc/SKILL.md"
+      target: ".codex/skills/spec-driver-doc/SKILL.md"
+
+claudeProjectOverrides:
+  classification: "project-override"
+  root: ".claude/commands"
+  note: "Kept for directory structure only. The 9 legacy atomic commands (spec-driver.{specify,plan,tasks,implement,clarify,analyze,checklist,constitution,taskstoissues}) were removed in v4.0, and the orchestrator skills no longer read .claude/commands/spec-driver.*.md as a prompt-source fallback. If such files still exist in a repository they will be ignored by the runtime. See docs/migrations/skill-deprecation.md."
+  entries: []

package/plugins/spec-driver/hooks/hooks.json

@@ -0,0 +1,70 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/postinstall.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/pre-tool-use-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use-format.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/stop-task-check.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeCreate": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/worktree-lifecycle.sh"
+          }
+        ]
+      }
+    ],
+    "WorktreeRemove": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/worktree-lifecycle.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/spec-driver/hooks/post-tool-use-format.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# PostToolUse Hook: Edit/Write 后自动 prettier 格式化
+# 仅对 JS/TS/JSON 文件生效，其他文件静默放行
+# 注意：密集编辑期间可能有性能开销。如需优化可改为 Stop hook 批量格式化。
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# 优先 jq，降级 grep+sed
+if command -v jq >/dev/null 2>&1; then
+  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // empty' 2>/dev/null || echo "")
+else
+  FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//' || echo "")
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+[ -f "$FILE_PATH" ] || exit 0
+
+case "$FILE_PATH" in
+  *.ts|*.tsx|*.js|*.jsx|*.json|*.mjs|*.cjs)
+    if command -v npx >/dev/null 2>&1; then
+      npx prettier --write "$FILE_PATH" >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+
+exit 0