sillyspec 3.20.2 → 3.20.3

package/.claude/skills/sillyspec-knowledge/SKILL.md

@@ -1,270 +0,0 @@
----
-name: sillyspec:knowledge
-description: Agent-safe knowledge base commands for SillySpec repositories. Search, inspect, validate, refresh, and propose knowledge entries.
-argument-hint: "search --query \"<text>\" --limit N | inspect --id \"<id>\" | validate | refresh | propose --title \"<title>\" --category <name>"
-version: "3.19.2"
----
-
-## 交互规范
-当需要用户从多个选项中做出选择时，必须使用 Claude Code 内置的 AskUserQuestion 工具，将选项以参数传入。
-
-## 何时使用此技能
-Use this skill when working on a SillySpec repository and the task may depend on prior project knowledge, known issues, implementation patterns, scan-derived learnings, execute-stage knowledge hits, or `.sillyspec/knowledge`.
-
-Before implementing changes, **first search the knowledge base** to avoid repeating known work or running into known issues.
-
-## 命令列表
-
-### 1. knowledge search — 搜索知识库
-在执行任务前搜索相关知识。
-
-```bash
-sillyspec knowledge search --query "<task summary>" --limit 5
-```
-
-**示例：**
-```bash
-sillyspec knowledge search --query "worktree baseline apply conflict" --limit 5
-sillyspec knowledge search --query "postcheck validation error"
-sillyspec knowledge search --query "GLM usage metadata"
-```
-
-**输出（JSON）：**
-```json
-{
-  "ok": true,
-  "query": "worktree baseline",
-  "matches": [
-    {
-      "id": "patterns",
-      "path": "knowledge/patterns.md",
-      "title": "Patterns",
-      "summary": "每个阶段对应 `src/stages/` 下的独立模块...",
-      "score": 3,
-      "tags": ["worktree", "git-worktree", "WorktreeManager"],
-      "category": "Patterns"
-    }
-  ]
-}
-```
-
-**使用场景：**
-- 实现新功能前，检查是否有现有模式可复用
-- 遇到报错前，搜索是否是已知问题
-- 修改特定模块前，了解约定和坑点
-
----
-
-### 2. knowledge inspect — 读取知识条目详情
-搜索命中后，读取完整条目内容。
-
-```bash
-sillyspec knowledge inspect --id "<knowledge-id>"
-```
-
-**示例：**
-```bash
-sillyspec knowledge inspect --id "patterns"
-sillyspec knowledge inspect --id "known-issues/sqljs-wasm-only"
-sillyspec knowledge inspect --id "generated/worktree-baseline-conflict"
-```
-
-**输出（JSON）：**
-```json
-{
-  "ok": true,
-  "entry": {
-    "id": "patterns",
-    "title": "Patterns",
-    "summary": "每个阶段对应 `src/stages/` 下的独立模块...",
-    "zone": "manual",
-    "path": "knowledge/patterns.md",
-    "meta": {
-      "author": "qinyi",
-      "created_at": "2026-06-19T12:40:00+08:00",
-      "updated_at": "2026-06-24T10:00:00+08:00"
-    },
-    "body": "完整 markdown 内容..."
-  }
-}
-```
-
-**zone 说明：**
-- `manual` — 人工维护的知识（可直接信任）
-- `generated` — 自动提取的知识（scan 生成，需人工审核）
-- `proposed` — 提议待审核的知识（未合并）
-
----
-
-### 3. knowledge validate — 校验知识库健康度
-在 commit/archive 前检查知识库是否可用。
-
-```bash
-sillyspec knowledge validate
-```
-
-**输出（JSON）：**
-```json
-{
-  "ok": false,
-  "errors": [
-    {
-      "code": "broken_reference",
-      "path": "knowledge/generated/foo.md",
-      "referenced_in": "INDEX.md",
-      "display": "Foo Pattern"
-    },
-    {
-      "code": "empty_file",
-      "path": "knowledge/bar.md"
-    }
-  ],
-  "warnings": [
-    {
-      "code": "too_many_uncategorized",
-      "count": 12,
-      "path": "knowledge/uncategorized.md"
-    },
-    {
-      "code": "unregistered_file",
-      "path": "knowledge/new-file.md"
-    }
-  ]
-}
-```
-
-**错误码说明：**
-| code | 说明 |
-|---|---|
-| `knowledge_dir_missing` | `.sillyspec/knowledge/` 目录不存在 |
-| `missing_index` | `INDEX.md` 不存在 |
-| `broken_reference` | INDEX.md 引用的文件不存在 |
-| `empty_file` | 知识文件为空 |
-| `too_many_uncategorized` | uncategorized.md 条目 ≥10，需清理 |
-| `unregistered_file` | 手动知识文件未在 INDEX.md 注册 |
-
----
-
-### 4. knowledge refresh — 从 scan 文档刷新自动知识
-**仅写 generated/ 区，不覆盖 manual/。**
-
-```bash
-sillyspec knowledge refresh
-```
-
-**使用场景：**
-- scan 阶段完成后，自动提取可复用知识
-- archive 阶段完成后，沉淀长期有效的模式
-
-**行为：**
-1. 扫描 `.sillyspec/docs/<project>/scan/*.md`
-2. 提取每个 `## 章节`（至少 3 行）作为知识条目
-3. 写入 `.sillyspec/knowledge/generated/<slug>.md`
-4. 生成 `generated/INDEX.md`
-
-**输出（JSON）：**
-```json
-{
-  "ok": true,
-  "generated_count": 8,
-  "new_count": 5,
-  "overwritten_count": 3,
-  "files": [
-    { "file": "generated/worktree-isolation.md", "title": "...", "new": true },
-    { "file": "generated/progress-management.md", "title": "...", "new": false }
-  ]
-}
-```
-
-**注意事项：**
-- generated/ 区知识是自动生成，不保证准确，需人工审核后合并到 manual/
-- 已有文件会被覆盖（ overwrite_count）
-
----
-
-### 5. knowledge propose — 提议新知识
-不直接编辑 manual/，而是写入 proposed/ 供审核。
-
-```bash
-sillyspec knowledge propose --title "<title>" --category <category> --body "<content>" --from "<source>"
-```
-
-**参数说明：**
-| 参数 | 必填 | 说明 |
-|---|---|---|
-| `--title` | ✅ | 知识标题 |
-| `--category` | ❌ | 分类（默认 uncategorized），如 known-issues, patterns, conventions |
-| `--body` | ❌ | 知识正文 |
-| `--from` | ❌ | 来源标注（如 execute/quick/scan） |
-
-**示例：**
-```bash
-sillyspec knowledge propose --title "GLM API 超时处理" --category known-issues --body "GLM 模型默认超时 30 秒..." --from "execute"
-```
-
-**输出（JSON）：**
-```json
-{
-  "ok": true,
-  "id": "proposed/glm-api-timeout",
-  "path": "knowledge/proposed/glm-api-timeout.md",
-  "title": "GLM API 超时处理",
-  "category": "known-issues",
-  "new": true,
-  "action": "created"
-}
-```
-
-**后续流程：**
-- archive/commit 阶段审核 proposed/ 条目
-- 合格的合并到 manual/，不合格的删除
-
----
-
-## Agent 使用指南
-
-### 任务前必查
-在开始实现新功能、修改现有代码、或遇到报错前：
-1. `knowledge search --query "<任务关键词>"`
-2. 命中则 `knowledge inspect --id "<id>"`
-3. 遵循知识中的约定和避坑建议
-
-### 发现新知识
-执行任务中发现可复用模式或新坑：
-1. `knowledge propose --title "<标题>" --category <分类> --body "<内容>"`
-2. 不要直接编辑 `.sillyspec/knowledge/manual/*.md`
-
-### 提交前校验
-commit/archive 前检查知识库状态：
-1. `knowledge validate`
-2. 如有 errors，先修复再提交
-
-### 扫描后刷新
-scan 阶段完成后：
-1. `knowledge refresh`
-2. 审核生成的 `generated/*.md`，有用的合并到 manual/
-
----
-
-## 禁止事项
-
-❌ **不要直接编辑** `manual/` 或 `generated/` 中的知识文件
-- 使用 `knowledge propose` 提议新知识
-- 使用 `knowledge refresh` 刷新自动知识
-
-❌ **不要使用 `grep` 或 `cat` 直接读取知识文件**
-- 使用 `knowledge search` 和 `knowledge inspect`
-- 它们使用与 execute 阶段相同的匹配引擎
-
-❌ **不要让 agent 去审核 proposed/ 条目**
-- 提议供人工审核，不要自动合并
-- 只有用户明确要求才合并
-
----
-
-## 设计原则
-
-- **Agent-safe：** 所有输出为 JSON，失败有明确错误码
-- **写保护：** refresh 仅写 generated/，propose 仅写 proposed/，不碰 manual/
-- **匹配引擎：** 使用 `knowledge-match.js`（与 execute 阶段一致）
-- **审计友好：** 每个条目记录来源、创建/更新时间

package/.husky/pre-push

@@ -1,13 +0,0 @@
-#!/bin/sh
-echo "🔧 pre-push: running lint + test..."
-npm run lint --silent 2>&1
-if [ $? -ne 0 ]; then
-  echo "❌ pre-push: lint failed, aborting push"
-  exit 1
-fi
-npm test --silent 2>&1
-if [ $? -ne 0 ]; then
-  echo "❌ pre-push: test failed, aborting push"
-  exit 1
-fi
-echo "✅ pre-push: lint + test passed"

package/CLAUDE.md

@@ -1,18 +0,0 @@
-# Claude Code 指引
-
-## 文件生命周期文档同步
-每次修改 `src/stages/` 下的阶段定义（prompt、步骤、输出文件名等）或 `src/run.js`、`src/progress.js` 等影响文件生命周期的代码后，**必须同步更新** `docs/sillyspec/file-lifecycle.md`，确保文档与代码一致。
-
-### 触发更新的典型改动
-- 新增/删除/重命名阶段步骤
-- 修改步骤 prompt 中的输出文件名（如 verify-result.md）
-- 修改阶段间的流转逻辑（如 archive 归档方式）
-- 新增/删除运行时文件类型（如 gate-status.json）
-- 修改 ProgressManager 的数据存储方式（如 SQLite 表结构变更）
-
-### 更新检查清单
-- [ ] 文件名引用一致（prompt 输出的文件名 == validateFileLocations 期望的文件名）
-- [ ] 阶段步骤描述与 `src/stages/*.js` 一致
-- [ ] 归档/清理流程描述与实际代码逻辑一致
-- [ ] 数据库 Schema 描述与 `src/db.js` 一致
-- [ ] 更新文档头部 `updated_at` 时间戳

package/docs/brainstorm-plan-contract.md

@@ -1,64 +0,0 @@
----
-author: qinyi
-created_at: 2026-06-19 00:45:00
----
-
-# Brainstorm → Plan Contract
-
-## 核心契约
-
-`design.md` 是 plan 阶段的**主要设计输入**。plan 不应该在空的或缺少关键决策的 design.md 上生成任务。
-
-## design.md 结构要求
-
-### 必须包含（error — 阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 1 | 目标/背景/问题描述 | 目标、goal、objective、背景、background、问题、problem、purpose、目的 |
-| 2 | 范围/总体方案/设计 | 范围、scope、总体方案、方案、approach、solution、设计、design |
-| 3 | 决策/方案选择 | 决策、decision、选择、choice、方案选择、D-xxx@vN（decisions.md 引用） |
-
-### 建议包含（warning — 不阻断 plan）
-
-| # | 章节 | 匹配关键词 |
-|---|------|-----------|
-| 4 | 非目标/Non-goals | 非目标、non-goals、不做、out of scope |
-| 5 | 约束/风险/Trade-off | 约束、constraint、风险、risk、trade-off |
-| 6 | 文件变更清单 | 文件变更、变更清单、changed files |
-
-## 校验规则
-
-plan 启动时（第一个步骤执行前）调用 `validateDesignForPlan(designContent)`：
-
-| 结果 | 行为 |
-|------|------|
-| 全部通过 | 正常进入 plan |
-| 有 warning | 继续执行，展示警告 |
-| 有 error | fail-fast，提示修复 design.md |
-
-## 第一版设计原则
-
-- **轻量 markdown 契约**：检查标题和关键词，不强 schema
-- **关键词宽泛**：中英文都支持
-- **decisions.md 引用也算决策**：`D-xxx@vN` 或 `decisions.md` 引用即满足决策检查
-- **不做 brainstorm postcheck 阻断**：brainstorm 完成时不校验此契约（brainstorm 可以产出不完整的 design.md），只在 plan 启动时校验
-
-## 错误处理
-
-| 场景 | 行为 |
-|------|------|
-| design.md 不存在 | 不校验（向后兼容，plan 可以独立运行） |
-| design.md 空 | fail-fast |
-| 缺目标/背景 | fail-fast |
-| 缺范围/方案 | fail-fast |
-| 缺决策 | fail-fast |
-| 缺非目标/约束/文件清单 | warning，继续执行 |
-
-## 完整契约链
-
-```
-brainstorm → design.md → [Plan Contract 校验] → plan → plan.md → [Execute Contract 校验] → execute
-```
-
-每个阶段启动前都校验上游产物，形成双重保险。

package/docs/plan-execute-contract.md

@@ -1,123 +0,0 @@
----
-author: qinyi
-created_at: 2026-06-19 00:25:00
----
-
-# Plan → Execute Contract
-
-## 核心契约
-
-`plan.md` 是 execute 阶段的**唯一任务蓝图输入**。execute 不从其他来源（brainstorm、tasks.md、agent 记忆）获取任务列表。
-
-## plan.md 格式要求
-
-### Checkbox Task（必须）
-
-execute 通过 checkbox 解析任务，格式：
-
-```markdown
-- [ ] task-01: 实现用户认证模块
-- [ ] task-02: 添加权限校验中间件
-- [ ] task-03: 编写集成测试
-```
-
-### Task ID 规则
-
-- 格式：`task-XX`（XX 为数字，建议两位补零）
-- 必须唯一：同一 plan.md 内不能有两个相同 task id
-- 建议连续：从 task-01 开始递增
-- 不能为空：每个 checkbox task 必须有 id
-
-### Task Name 规则
-
-- 必须非空
-- 清晰描述任务内容
-
-### Wave 分组
-
-```markdown
-## Wave 1
-- [ ] task-01: 搭建项目骨架
-- [ ] task-02: 配置 CI/CD
-
-## Wave 2
-- [ ] task-03: 实现业务逻辑
-```
-
-- Wave 内任务无依赖（可并行）
-- Wave 间有依赖（按序执行）
-- Wave 只能引用已存在的 task
-
-## 校验规则
-
-execute 进入前调用 `validatePlanForExecute(planContent)`：
-
-| # | 规则 | 级别 |
-|---|------|------|
-| 1 | plan.md 非空 | error |
-| 2 | 至少有一个 checkbox task | error |
-| 3 | task id 唯一 | error |
-| 4 | task id 连续（task-01 起） | error |
-| 5 | task name 非空 | error |
-| 6 | task 有 id（无 id 只 warning） | warning |
-
-校验失败 → fail-fast，不进入 execute。
-校验通过但有 warning → 继续执行，提示警告。
-
-## 复杂度场景
-
-### none（最小变更）
-```markdown
-## Wave 1
-- [ ] task-01: 修复 bug
-```
-至少 1 个 checkbox task。
-
-### light（轻量变更）
-```markdown
-## Wave 1
-- [ ] task-01: 添加 API 端点
-- [ ] task-02: 添加前端调用
-```
-1 个 Wave，2-3 个 task。
-
-### full（完整变更）
-```markdown
-## Wave 1: 基础设施
-- [ ] task-01: 数据库 schema
-- [ ] task-02: 模型定义
-
-## Wave 2: 业务逻辑
-- [ ] task-03: API 实现
-- [ ] task-04: 业务规则
-
-## Wave 3: 测试
-- [ ] task-05: 集成测试
-```
-多个 Wave，每个 Wave 1-N 个 task。
-
-## execute reopen 契约
-
-当 execute 被 `--reopen` 时：
-1. **必须从最新 plan.md 重新解析 steps**（不复用旧 task/wave）
-2. 如果 plan.md 已变更（wave 数量变了），execute steps 会反映最新状态
-3. 旧 completed steps 不保留（全部回到 pending/stale）
-
-## 错误处理
-
-| 场景 | 行为 |
-|------|------|
-| plan.md 不存在 | 生成默认 3 Wave（向后兼容） |
-| plan.md 存在但无 checkbox | fail-fast |
-| task id 重复 | fail-fast |
-| task id 不连续 | fail-fast |
-| plan.md 被修改后 execute reopen | 重新解析，使用最新 wave/task |
-
-## 双重校验
-
-契约在两个时点执行：
-
-1. **plan 完成时**（plan postcheck）：plan.md 不合法 → 阻断 completed，plan 阶段无法完成
-2. **execute 启动时**（execute entry）：plan.md 不合法 → fail-fast，不进入 execute
-
-这确保 plan.md 在进入 execute 之前就是合法的，execute 启动时的校验是二次保险。