sillyspec 3.22.2 → 3.22.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/.claude/skills/sillyspec-doctor/SKILL.md +65 -61
  2. package/.claude/skills/sillyspec-quick/SKILL.md +84 -84
  3. package/package.json +1 -1
  4. package/src/doctor-diagnostics.js +696 -575
  5. package/src/index.js +65 -0
  6. package/src/progress.js +111 -0
  7. package/src/run.js +26 -9
  8. package/src/worktree-apply.js +2 -4
  9. package/src/worktree.js +37 -3
package/.claude/skills/sillyspec-doctor/SKILL.md CHANGED
@@ -1,61 +1,65 @@
1
- ---
2
- name: sillyspec:doctor
3
- description: 用于 SillySpec 自检和状态修复。适合用户说"检查下状态、修复 progress、doctor、状态不对"。全量扫描进度一致性，修复进度数据与实际产出不匹配的问题。
4
- ---
5
-
6
- ## 何时使用
7
-
8
- - 用户说"检查下状态、修复 progress、doctor、状态不对"
9
- - 进度数据与实际产出不匹配时自检修复
10
- - 5 步：环境检查 → 项目配置 → 数据库完整性 → 状态一致性 → 修复建议
11
-
12
- ## 前置检查
13
-
14
- **执行任何步骤前，先确认 SillySpec CLI 可用：**
15
-
16
- ```bash
17
- sillyspec --version
18
- ```
19
-
20
- 失败则提示 `❌ SillySpec CLI 未安装` + 安装命令 `npm install -g sillyspec`，停止。
21
-
22
- ## 步骤生命周期（所有阶段通用）
23
-
24
- > `sillyspec doctor` 是 `sillyspec run doctor` 的顶层别名，两者等价。
25
-
26
- ```bash
27
- sillyspec run doctor # 输出当前步骤 prompt
28
- sillyspec run doctor --done --output "摘要" # 完成当前步骤
29
- sillyspec run doctor --status # 查看阶段进度
30
- sillyspec run doctor --reset # 重置阶段（从头开始）
31
- ```
32
-
33
- ## 通用参数（所有阶段适用）
34
-
35
- | 参数 | 说明 |
36
- |---|---|
37
- | `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
38
- | `--non-interactive` | CI/脚本下禁用交互式 prompt |
39
- | `--json` | 输出 JSON（程序化读取） |
40
-
41
- ## doctor 特有
42
-
43
- doctor 是辅助阶段，用于诊断而非推进流程。配套的轻量诊断命令（不经 run）：
44
-
45
- ```bash
46
- sillyspec progress show # 查看当前进度
47
- sillyspec progress check # 状态一致性检查（只报告，不修复）
48
- sillyspec progress repair # 修复状态元数据（dry-run）
49
- sillyspec progress repair --apply # 真正修复
50
- sillyspec progress validate # 校验并修复
51
- sillyspec worktree doctor [--fix] # worktree 健康检查 + 修复
52
- ```
53
-
54
- ## 铁律
55
-
56
- - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
57
- - doctor 只诊断和建议，修复操作要让用户确认
58
- - 完成后立即 `--done`，不跳过
59
-
60
- ## 用户指令
61
- $ARGUMENTS
1
+ ---
2
+ name: sillyspec:doctor
3
+ description: 用于 SillySpec 自检和状态修复。适合用户说"检查下状态、修复 progress、doctor、状态不对"。全量扫描进度一致性，修复进度数据与实际产出不匹配的问题。
4
+ ---
5
+
6
+ ## 何时使用
7
+
8
+ - 用户说"检查下状态、修复 progress、doctor、状态不对"
9
+ - 进度数据与实际产出不匹配时自检修复
10
+ - 5 步：环境检查 → 项目配置 → 数据库完整性 → 状态一致性 → 修复建议
11
+
12
+ ## 前置检查
13
+
14
+ **执行任何步骤前，先确认 SillySpec CLI 可用：**
15
+
16
+ ```bash
17
+ sillyspec --version
18
+ ```
19
+
20
+ 失败则提示 `❌ SillySpec CLI 未安装` + 安装命令 `npm install -g sillyspec`，停止。
21
+
22
+ ## 步骤生命周期（所有阶段通用）
23
+
24
+ > `sillyspec doctor` 是 `sillyspec run doctor` 的顶层别名，两者等价。
25
+
26
+ ```bash
27
+ sillyspec run doctor # 输出当前步骤 prompt
28
+ sillyspec run doctor --done --output "摘要" # 完成当前步骤
29
+ sillyspec run doctor --status # 查看阶段进度
30
+ sillyspec run doctor --reset # 重置阶段（从头开始）
31
+ ```
32
+
33
+ ## 通用参数（所有阶段适用）
34
+
35
+ | 参数 | 说明 |
36
+ |---|---|
37
+ | `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
38
+ | `--non-interactive` | CI/脚本下禁用交互式 prompt |
39
+ | `--json` | 输出 JSON（程序化读取） |
40
+
41
+ ## doctor 特有
42
+
43
+ doctor 是辅助阶段，用于诊断而非推进流程。配套的轻量诊断命令（不经 run）：
44
+
45
+ ```bash
46
+ sillyspec progress show # 查看当前进度
47
+ sillyspec progress check # 状态一致性检查（只报告，不修复）
48
+ sillyspec progress repair # 修复状态元数据（dry-run）
49
+ sillyspec progress repair --apply # 真正修复
50
+ sillyspec progress validate # 校验并修复
51
+ sillyspec worktree doctor [--fix] # worktree 健康检查 + 修复
52
+ sillyspec doctor --align-execute-progress --change <name> # 按 plan.md 声明对齐 execute 派生戳（dry-run，只报告将补哪些 step）
53
+ sillyspec doctor --align-execute-progress --change <name> --confirm # 实际落盘：补 step 戳 + 置 execute stage status=completed
54
+ ```
55
+
56
+ > `--align-execute-progress` 仅当 `plan.md` 所有 task checkbox 全勾时才对齐 execute 阶段进度戳。典型用于 worktree 已 cleanup（终态）但 execute 派生戳未盖上的死锁。默认 dry-run，加 `--confirm` 才写盘。doctor 信任 `plan.md` 声明、不复核代码，verify 阶段兜底。`--change` 缺省时按单活跃变更自动兜底。
57
+
58
+ ## 铁律
59
+
60
+ - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
61
+ - doctor 只诊断和建议，修复操作要让用户确认
62
+ - 完成后立即 `--done`，不跳过
63
+
64
+ ## 用户指令
65
+ $ARGUMENTS
package/.claude/skills/sillyspec-quick/SKILL.md CHANGED
@@ -1,84 +1,84 @@
1
- ---
2
- name: sillyspec:quick
3
- description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
4
- ---
5
-
6
- ## 何时使用
7
-
8
- - 明确、低风险、范围小的直接修改：改文案、修小 bug、更新单个文件
9
- - 用户说"直接改、快速修、顺手调整、不要完整流程"
10
- - 跳过 brainstorm/plan，但仍走 quick 的 3 步流程（理解任务 → 实现 → 自检提交）
11
-
12
- ## 多变更说明（quick 特殊，务必注意）
13
-
14
- quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置**，**不要用 `--change` 来指定关联变更**。多活跃变更时改用：
15
-
16
- - `--linked-changes none`：不关联，仅记 QUICKLOG
17
- - `--linked-changes a,b`：显式关联到变更 a、b
18
- - `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
19
-
20
- 首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-guard.json`，后续 `--done` 自动复用，**不会重复弹交互 prompt**。
21
-
22
- ## 步骤生命周期（所有阶段通用）
23
-
24
- > `sillyspec quick` 是 `sillyspec run quick` 的顶层别名，两者等价。
25
-
26
- ```bash
27
- sillyspec run quick # 输出当前步骤 prompt（首次会记录 baseline）
28
- sillyspec run quick --done --output "摘要" # 完成当前步骤
29
- sillyspec run quick --status # 查看阶段进度
30
- sillyspec run quick --skip # 跳过可选步骤
31
- sillyspec run quick --reset # 重置阶段（从头开始）
32
- sillyspec run quick --reopen --from-step N # 重新打开已完成阶段修订（N=序号或名称）
33
- ```
34
-
35
- ## 通用参数（所有阶段适用）
36
-
37
- | 参数 | 说明 |
38
- |---|---|
39
- | `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
40
- | `--non-interactive` | CI/脚本下禁用交互式 prompt |
41
- | `--interactive` | 强制交互（即便 stdin 非 TTY） |
42
- | `--skip-approval` | 跳过审批/校验门控（需明确意图） |
43
- | `--json` | 输出 JSON（程序化读取） |
44
-
45
- ## quick 特有参数
46
-
47
- | 参数 | 说明 |
48
- |---|---|
49
- | `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
50
- | `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护） |
51
- | `--allow-new` | 允许新增文件（默认禁止，防意外创建） |
52
- | `--force-baseline` | 允许覆盖 baseline 受保护文件（危险，慎用） |
53
- | `--confirm` | 完成时确认接受变更审计结果（warning/blocked 时用） |
54
-
55
- ## 典型用法
56
-
57
- ```bash
58
- # 单变更项目，直接开始
59
- sillyspec run quick
60
-
61
- # 多变更项目，显式不关联
62
- sillyspec run quick --linked-changes none
63
-
64
- # 多变更项目，关联到指定变更
65
- sillyspec run quick --linked-changes 2026-07-03-add-login
66
-
67
- # CI/脚本（非交互，避免 prompt 崩溃）
68
- sillyspec run quick --non-interactive
69
- sillyspec run quick --done --linked-changes none --output "修复手机号校验"
70
-
71
- # 限定修改文件范围
72
- sillyspec run quick --files src/phone.ts,src/phone.test.ts
73
- ```
74
-
75
- ## 铁律
76
-
77
- - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
78
- - quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
79
- - 完成后立即 `--done`，不跳过
80
- - step 2 会创建 `.sillyspec/quicklog/QUICKLOG-<user>.md` 记录，完成前 CLI 会校验它存在
81
- - **禁止**在没有运行 CLI 的情况下自行决定流程
82
-
83
- ## 用户指令
84
- $ARGUMENTS
1
+ ---
2
+ name: sillyspec:quick
3
+ description: 用于明确、低风险、范围很小的直接任务。适合用户说"直接改、快速修、顺手调整、改个文案、修个小 bug、更新一个文件、不要完整流程"。跳过 brainstorm/plan，但仍按 sillyspec quick 流程执行。
4
+ ---
5
+
6
+ ## 何时使用
7
+
8
+ - 明确、低风险、范围小的直接修改：改文案、修小 bug、更新单个文件
9
+ - 用户说"直接改、快速修、顺手调整、不要完整流程"
10
+ - 跳过 brainstorm/plan，但仍走 quick 的 3 步流程（理解任务 → 实现 → 自检提交）
11
+
12
+ ## 多变更说明（quick 特殊，务必注意）
13
+
14
+ quick 阶段的 `--change` 语义是「关联变更」**且会触发步骤重置**，**不要用 `--change` 来指定关联变更**。多活跃变更时改用：
15
+
16
+ - `--linked-changes none`：不关联，仅记 QUICKLOG
17
+ - `--linked-changes a,b`：显式关联到变更 a、b
18
+ - `--non-interactive`：CI/脚本环境，默认不关联（避免交互 prompt 崩溃）
19
+
20
+ 首次 `sillyspec run quick` 选定的关联会持久化到 `.runtime/quick-guard.json`，后续 `--done` 自动复用，**不会重复弹交互 prompt**。
21
+
22
+ ## 步骤生命周期（所有阶段通用）
23
+
24
+ > `sillyspec quick` 是 `sillyspec run quick` 的顶层别名，两者等价。
25
+
26
+ ```bash
27
+ sillyspec run quick # 输出当前步骤 prompt（首次会记录 baseline）
28
+ sillyspec run quick --done --output "摘要" # 完成当前步骤
29
+ sillyspec run quick --status # 查看阶段进度
30
+ sillyspec run quick --skip # 跳过可选步骤
31
+ sillyspec run quick --reset # 重置阶段（从头开始）
32
+ sillyspec run quick --reopen --from-step N # 重新打开已完成阶段修订（N=序号或名称）
33
+ ```
34
+
35
+ ## 通用参数（所有阶段适用）
36
+
37
+ | 参数 | 说明 |
38
+ |---|---|
39
+ | `--spec-dir <path>` | 指定规范目录（默认 `<项目>/.sillyspec`） |
40
+ | `--non-interactive` | CI/脚本下禁用交互式 prompt |
41
+ | `--interactive` | 强制交互（即便 stdin 非 TTY） |
42
+ | `--skip-approval` | 跳过审批/校验门控（需明确意图） |
43
+ | `--json` | 输出 JSON（程序化读取） |
44
+
45
+ ## quick 特有参数
46
+
47
+ | 参数 | 说明 |
48
+ |---|---|
49
+ | `--linked-changes none\|a,b` | **显式关联变更（取代 `--change`，推荐）**。none=不关联，a,b=关联列表 |
50
+ | `--files a.js,b.js` | 显式声明本次允许修改的文件（边界保护） |
51
+ | `--allow-new` | 允许新增文件（默认禁止，防意外创建） |
52
+ | `--force-baseline` | 允许覆盖 baseline 受保护文件（危险，慎用） |
53
+ | `--confirm` | 完成时确认接受变更审计结果（warning/blocked 时用） |
54
+
55
+ ## 典型用法
56
+
57
+ ```bash
58
+ # 单变更项目，直接开始
59
+ sillyspec run quick
60
+
61
+ # 多变更项目，显式不关联
62
+ sillyspec run quick --linked-changes none
63
+
64
+ # 多变更项目，关联到指定变更
65
+ sillyspec run quick --linked-changes 2026-07-03-add-login
66
+
67
+ # CI/脚本（非交互，避免 prompt 崩溃）
68
+ sillyspec run quick --non-interactive
69
+ sillyspec run quick --done --linked-changes none --output "修复手机号校验"
70
+
71
+ # 限定修改文件范围
72
+ sillyspec run quick --files src/phone.ts,src/phone.test.ts
73
+ ```
74
+
75
+ ## 铁律
76
+
77
+ - **必须用 exec 工具（shell）执行 CLI，不要自己编造流程**
78
+ - quick 直接在主工作区改代码（不创建 worktree），范围必须小且明确
79
+ - 完成后立即 `--done`，不跳过
80
+ - step 1 会创建 `.sillyspec/quicklog/QUICKLOG-<user>.md` 记录（理解任务时），完成前 CLI 会校验它存在
81
+ - **禁止**在没有运行 CLI 的情况下自行决定流程
82
+
83
+ ## 用户指令
84
+ $ARGUMENTS
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "sillyspec",
3
- "version": "3.22.2",
3
+ "version": "3.22.4",
4
4
  "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
5
5
  "icon": "logo.jpg",
6
6
  "homepage": "https://sillyspec.ppdmq.top/",