sillyspec 3.18.3 → 3.18.5

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

@@ -68,7 +68,7 @@ $ARGUMENTS
 
 ### 关键规则
 - 不要跳过任何步骤
-- 不要手动修改 progress.json
+- 不要手动修改进度数据（SQLite 数据库）
 - 不要自动 commit，只 git add
 - 不要使用 npx
 - 不要编造不存在的 CLI 子命令

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

@@ -1,6 +1,6 @@
 ---
 name: sillyspec:doctor
-description: 用于 SillySpec 自检和状态修复。适合用户说"检查下状态、修复 progress、doctor、状态不对"。全量扫描进度一致性，修复 progress.json 与实际产出不匹配的问题。
+description: 用于 SillySpec 自检和状态修复。适合用户说"检查下状态、修复 progress、doctor、状态不对"。全量扫描进度一致性，修复进度数据与实际产出不匹配的问题。
 ---
 
 ## 前置检查

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

@@ -23,6 +23,8 @@ description: 用于按 plan 执行代码实现。适合用户说"开始写代码
 - Worktree 路径在 Step 3（确认 worktree 路径）中输出，后续子代理的 cwd 必须设为该路径
 - **禁止跳过 worktree 或在主仓库直接写代码**
 - 如果 worktree 创建失败，CLI 会报错并退出，需要排查后再重试
+- **未提交的文件、dirty 状态等不影响 worktree 创建和进入，直接按 CLI 输出的 worktree 路径操作即可**
+- 不要自行检查 git 状态来判断是否可以进入 worktree，CLI 会自动处理
 
 ## 用户指令
 $ARGUMENTS

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

@@ -22,15 +22,15 @@ description: 恢复工作 — 从中断处继续
 sillyspec progress show
 ```
 
-### 2. 如果有 progress.json
+### 2. 如果有活跃变更
 
-从 progress.json 中提取并展示当前状态，使用 `sillyspec progress show` 查看。
+从 `sillyspec progress show` 输出中提取并展示当前状态。
 
 然后问用户：
    1. 直接继续执行下一步
    2. 查看更多细节
 
-### 3. 如果没有 progress.json 或变更目录
+### 3. 如果没有活跃变更
 
 自动探测项目状态：
 
@@ -64,5 +64,5 @@ cat .sillyspec/ROADMAP.md 2>/dev/null
 
 ### 4. 关键原则
 
-- progress.json 是唯一的恢复数据源（存储在 `.sillyspec/changes/<name>/progress.json` 或旧版 `.sillyspec/.runtime/progress.json`）
-- progress.json 随 `sillyspec run <stage> --done` 自动更新，不需要手动保存
+- 进度数据存储在 SQLite 数据库中（`.sillyspec/.runtime/sillyspec.db`），通过 `sillyspec progress show` 命令查看
+- 进度随 `sillyspec run <stage> --done` 自动更新，不需要手动保存

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

@@ -1,19 +1,19 @@
 ---
 name: sillyspec:state
-description: 查看当前工作状态 — 显示 progress.json 内容
+description: 查看当前工作状态 — 显示 SillySpec 进度
 ---
 
 你现在是 SillySpec 的状态查看器。
 
 ## 流程
 
-### 1. 读取 progress.json
+### 1. 读取进度
 
 ```bash
-sillyspec run state --status 2>/dev/null
+sillyspec progress show
 ```
 
-### 2. 如果有 progress.json
+### 2. 如果有活跃变更
 
 格式化展示当前状态：
 
@@ -33,9 +33,9 @@ sillyspec run state --status 2>/dev/null
 > **阻塞项**：
 > - xxx（如无则省略）
 
-### 3. 如果没有 progress.json
+### 3. 如果没有活跃变更
 
-提示用户项目还没有开始，或 progress.json 尚未生成：
+提示用户项目还没有开始：
 
 > 📊 还没有工作记录。
 >
@@ -44,11 +44,11 @@ sillyspec run state --status 2>/dev/null
 > - 已有项目：`/sillyspec:scan`
 > - 恢复中断的工作：`/sillyspec:resume`
 >
-> progress.json 会在 `sillyspec init` 时自动创建。
+> 进度数据会在 `sillyspec init` 时自动创建到 SQLite 数据库中。
 
 ### 注意
 
 - 这是只读命令，**不修改任何文件**
 - `/sillyspec:status` 查看项目整体进度（change 文件级别）
-- `/sillyspec:state` 查看当前工作状态（progress.json 级别）
+- `/sillyspec:state` 查看当前工作状态（阶段/步骤级别）
 - 两者互补：status 看"有什么"，state 看"在做什么"

package/docs/sillyspec/file-lifecycle/storage-and-state.md

@@ -43,7 +43,7 @@ created_at: 2026-06-04 16:25:42
 | `batch_progress` | 批量任务统计 |
 | `approvals` | 平台审批状态 |
 
-`progress.js` 通过 SQL 读写这些表，并组装成兼容旧 progress JSON 的 JS 对象。当前没有看到 `progress.json` 被作为权威状态写入。
+`progress.js` 通过 SQL 读写这些表，并组装成兼容旧 progress 格式的 JS 对象。进度数据仅存储在 SQLite 数据库中，不再使用 progress.json 文件。
 
 注意：`db.js` 的 `project.schema_version` DDL 默认值是 `4`，但 `progress.js` 的 `CURRENT_VERSION` 是 `3`，并在初始化/写入时使用 `3`。文档不要把这里写成稳定的 v4 schema 事实。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.18.3",
+  "version": "3.18.5",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/packages/dashboard/server/index.js

@@ -48,12 +48,13 @@ function startProgressWatch(projectPath) {
     progressWatchers.get(projectPath).refCount++
     return
   }
-  const progressFile = join(projectPath, '.sillyspec', '.runtime', 'progress.json')
-  if (!existsSync(progressFile)) return
+  // Watch the SQLite database file for changes (replaces old progress.json watch)
+  const dbFile = join(projectPath, '.sillyspec', '.runtime', 'sillyspec.db')
+  if (!existsSync(dbFile)) return
 
   let timer = null
   try {
-    const watcher = watch(progressFile, (eventType) => {
+    const watcher = watch(dbFile, (eventType) => {
       if (timer) clearTimeout(timer)
       timer = setTimeout(() => {
         timer = null

package/packages/dashboard/server/parser.js

@@ -77,18 +77,13 @@ export function parseProjectOverview(projectPath) {
 
   // --- Last active ---
   const sillyspecDir = join(projectPath, '.sillyspec')
-  const progressPath = join(sillyspecDir, '.runtime', 'progress.json')
-  if (existsSync(progressPath)) {
+  // Progress is stored in SQLite (.sillyspec/.runtime/sillyspec.db), not progress.json
+  // Use mtime of the DB file as a fallback for lastActive
+  const dbPath = join(sillyspecDir, '.runtime', 'sillyspec.db')
+  if (existsSync(dbPath)) {
     try {
-      const progress = JSON.parse(readFileSync(progressPath, 'utf-8'))
-      if (progress.stages) {
-        for (const stageData of Object.values(progress.stages)) {
-          if (stageData.lastActive && (!result.lastActive || new Date(stageData.lastActive) > new Date(result.lastActive))) {
-            result.lastActive = stageData.lastActive
-          }
-        }
-      }
-      if (progress.lastActive) result.lastActive = progress.lastActive
+      const s = statSync(dbPath)
+      result.lastActive = s.mtime.toISOString()
     } catch {}
   }
   if (!result.lastActive) {
@@ -432,81 +427,46 @@ export function parseSillyspecDocsTree(projectPath) {
 }
 
 /**
- * Parse project state from .sillyspec directory
+ * Parse project state from .sillyspec SQLite database via CLI.
+ * Progress data is stored in SQLite (.sillyspec/.runtime/sillyspec.db),
+ * accessed through `sillyspec progress show`.
  * @param {string} projectPath - Path to the project directory
- * @returns {object} Project state with currentStage, nextStep, progress, stages, specs, lastActive
+ * @returns {object|null} Project state with currentStage, stages, lastActive
  */
 export function parseProjectState(projectPath) {
   const sillyspecDir = join(projectPath, '.sillyspec')
+  const dbPath = join(sillyspecDir, '.runtime', 'sillyspec.db')
 
-  if (!existsSync(sillyspecDir)) {
+  if (!existsSync(sillyspecDir) || !existsSync(dbPath)) {
     return null
   }
 
   let currentStage = ''
-  let nextStep = null
-  let progress = { stages: {} }
-  let stages = []
-  let specs = []
   let lastActive = null
 
-  // Read progress.json for current stage
-  const progressPath = join(sillyspecDir, '.runtime', 'progress.json')
-  if (existsSync(progressPath)) {
-    try {
-      const progressData = JSON.parse(readFileSync(progressPath, 'utf-8'))
-      progress = progressData
-      currentStage = progressData.currentStage || ''
-      stages = Object.keys(progressData.stages || {})
-
-      // Find last active
-      if (progressData.lastActive) lastActive = progressData.lastActive
-      if (progressData.stages) {
-        for (const [stageName, stageData] of Object.entries(progressData.stages)) {
-          if (stageData.lastActive || stageData.startedAt) {
-            const t = stageData.lastActive || stageData.startedAt
-            if (!lastActive || new Date(t) > new Date(lastActive)) lastActive = t
-          }
-        }
-      }
-    } catch (err) {
-      // Progress file exists but couldn't be parsed
-    }
-  }
+  // Use DB file mtime as lastActive indicator
+  try {
+    const s = statSync(dbPath)
+    lastActive = s.mtime.toISOString()
+  } catch {}
 
-  // List all spec files
-  const specsDir = join(sillyspecDir, 'specs')
-  if (existsSync(specsDir)) {
-    try {
-      const specFiles = readdirSync(specsDir)
-        .filter(f => f.endsWith('.md'))
-        .sort()
-
-      specs = specFiles.map(f => {
-        const specPath = join(specsDir, f)
-        try {
-          const content = readFileSync(specPath, 'utf-8')
-          const titleMatch = content.match(/^#\s+(.+)$/m)
-          return {
-            name: f,
-            title: titleMatch ? titleMatch[1] : f,
-            path: specPath
-          }
-        } catch {
-          return { name: f, title: f, path: specPath }
-        }
-      })
-    } catch (err) {
-      // Specs directory couldn't be read
-    }
+  // Use CLI to read current stage from SQLite
+  try {
+    const output = execSync('sillyspec progress show 2>/dev/null', {
+      cwd: projectPath, encoding: 'utf-8', timeout: 5000
+    })
+    const stageMatch = output.match(/当前阶段:\s*(\S+)/)
+    if (stageMatch) currentStage = stageMatch[1]
+  } catch {
+    // CLI unavailable or no active change
   }
 
   return {
     currentStage,
-    nextStep,
-    progress,
-    stages,
-    specs,
+    nextStep: null,
+    progress: { stages: {} },
+    stages: [],
+    specs: [],
     lastActive
   }
 }

package/src/contract-matrix.js

@@ -0,0 +1,278 @@
+/**
+ * contract-matrix.js — API Contract Matrix 生成与注入
+ *
+ * plan 阶段：识别 task 之间的 provider/consumer 关系，生成契约矩阵
+ * execute 阶段：
+ *   - 后端 task 完成后自动提取 endpoint artifact
+ *   - 前端 task 开始时注入上游契约
+ * verify 阶段：读取 artifact 做 parity check
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs'
+import { join, resolve, basename, relative } from 'path'
+import {
+  scanBackendEndpoints,
+  scanFrontendApiCalls,
+  normalizePath,
+} from './endpoint-extractor.js'
+
+// ─── 关键词检测 ─────────────────────────────────────────────────────────
+
+const PROVIDER_KEYWORDS = /router|routes|endpoint|api|backend|controller|fastapi|flask|express|koa|spring/i
+const CONSUMER_KEYWORDS = /frontend|client|service|apiFetch|request|fetch|axios|http/i
+
+/**
+ * 判断一个 task 文档是 provider（产出 API）还是 consumer（消费 API）
+ * @param {string} taskContent - task markdown 内容
+ * @returns {{ isProvider: boolean, isConsumer: boolean, confidence: number }}
+ */
+export function classifyTask(taskContent) {
+  const isProvider = PROVIDER_KEYWORDS.test(taskContent)
+  const isConsumer = CONSUMER_KEYWORDS.test(taskContent)
+  // 避免所有 task 都被标记（因为几乎所有 task 都含 "api"）
+  // 加强判定：provider 要命中 router/endpoint/backend/controller + api
+  // consumer 要命中 frontend/client/apiFetch + api
+  const providerStrong = /router|endpoint|backend|controller|fastapi|flask/i.test(taskContent)
+  const consumerStrong = /frontend|apiFetch|axios|api.*client/i.test(taskContent)
+  const providerConfidence = providerStrong ? 0.8 : (isProvider ? 0.4 : 0)
+  const consumerConfidence = consumerStrong ? 0.8 : (isConsumer ? 0.4 : 0)
+  return {
+    isProvider: providerConfidence >= 0.4,
+    isConsumer: consumerConfidence >= 0.4,
+    confidence: Math.max(providerConfidence, consumerConfidence),
+  }
+}
+
+/**
+ * 从 plan.md 解析 task 依赖关系，识别 provider → consumer 对
+ * @param {string} planContent - plan.md 内容
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @returns {Array<{ provider: string, consumer: string, type: string }>}
+ */
+export function buildContractMatrix(planContent, changeDir) {
+  const contracts = []
+
+  // 解析 task 依赖关系
+  // 格式: - [ ] task-04: ... (depends_on: [task-01]) 或
+  //        | task-04 | ... | 01 |
+  const taskDeps = parseTaskDependencies(planContent)
+
+  // 读取各 task 文档，分类 provider/consumer
+  const taskClasses = {}
+  for (const taskName of Object.keys(taskDeps)) {
+    const taskFile = join(changeDir, 'tasks', `${taskName}.md`)
+    if (existsSync(taskFile)) {
+      taskClasses[taskName] = classifyTask(readFileSync(taskFile, 'utf8'))
+    }
+  }
+
+  // 识别契约对：A depends_on B，且 A 是 consumer，B 是 provider
+  for (const [consumer, deps] of Object.entries(taskDeps)) {
+    const consumerClass = taskClasses[consumer]
+    if (!consumerClass?.isConsumer) continue
+
+    for (const provider of deps) {
+      const providerClass = taskClasses[provider]
+      if (!providerClass?.isProvider) continue
+
+      // 避免自引用和重复
+      if (consumer === provider) continue
+      const alreadyExists = contracts.some(
+        c => c.provider === provider && c.consumer === consumer
+      )
+      if (alreadyExists) continue
+
+      contracts.push({
+        provider,
+        consumer,
+        type: 'api',
+      })
+    }
+  }
+
+  return contracts
+}
+
+/**
+ * 从 plan.md 解析 task 依赖关系
+ * @param {string} planContent
+ * @returns {Record<string, string[]>} task → depends_on list
+ */
+function parseTaskDependencies(planContent) {
+  const deps = {}
+
+  // 方式 1: 表格形式 | task-04 | ... | 01,02 |
+  const tableRows = planContent.matchAll(/\|[^|]*task-(\d+)[^|]*\|[^|]*\|[^|]*(?:task-)?(\d+(?:\s*[,，]\s*\d+)*)[^|]*\|/gi)
+  for (const match of tableRows) {
+    const task = `task-${match[1]}`
+    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
+    deps[task] = depList
+  }
+
+  // 方式 2: depends_on 关键字
+  const dependsPattern = planContent.matchAll(/task-(\d+).*?depends_on.*?(\d+(?:\s*[,，]\s*\d+)*)/gi)
+  for (const match of dependsPattern) {
+    const task = `task-${match[1]}`
+    const depList = match[2].split(/[,，\s]+/).map(d => `task-${d.trim()}`).filter(d => d.startsWith('task-'))
+    if (!deps[task]) deps[task] = []
+    for (const d of depList) {
+      if (!deps[task].includes(d)) deps[task].push(d)
+    }
+  }
+
+  return deps
+}
+
+// ─── Execute 阶段：后端 task 完成后提取 artifact ───────────────────────
+
+/**
+ * 后端 task 完成后，扫描变更文件提取 endpoint artifact
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} worktreePath - worktree 路径（扫描源码用）
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} taskName - task-04
+ * @returns {{ ok: boolean, endpoints: Array, artifactPath: string|null }}
+ */
+export function extractProviderArtifact(changeDir, worktreePath, specBase, taskName) {
+  const artifactDir = join(specBase, '.runtime', 'contract-artifacts', taskName)
+  const artifactPath = join(artifactDir, 'endpoints.json')
+
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return { ok: false, endpoints: [], artifactPath: null, error: 'worktree not found' }
+  }
+
+  try {
+    const endpoints = scanBackendEndpoints(worktreePath)
+
+    if (endpoints.length > 0) {
+      mkdirSync(artifactDir, { recursive: true })
+      const artifact = {
+        task: taskName,
+        type: 'backend_endpoints',
+        extractedAt: new Date().toISOString(),
+        endpoints: endpoints.map(e => ({
+          method: e.method,
+          path: normalizePath(e.path),
+          source: relative(worktreePath, e.source),
+          line: e.line,
+        })),
+      }
+      writeFileSync(artifactPath, JSON.stringify(artifact, null, 2) + '\n')
+      return { ok: true, endpoints: artifact.endpoints, artifactPath }
+    }
+
+    // 无端点提取到 — 不算错误（可能不是 router task）
+    return { ok: true, endpoints: [], artifactPath: null }
+  } catch (e) {
+    return { ok: false, endpoints: [], artifactPath: null, error: e.message }
+  }
+}
+
+// ─── Execute 阶段：前端 task 开始时注入契约 ─────────────────────────────
+
+/**
+ * 为 consumer task 构建上游契约注入文本
+ * @param {string} changeDir - changes/<name>/ 目录
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} taskName - 当前 task（consumer）
+ * @param {Array<{ provider: string, consumer: string, type: string }>} contracts
+ * @returns {string|null} 注入到 prompt 的契约文本，无契约时返回 null
+ */
+export function buildConsumerInjection(changeDir, specBase, taskName, contracts) {
+  const myContracts = contracts.filter(c => c.consumer === taskName)
+  if (myContracts.length === 0) return null
+
+  const parts = []
+  for (const contract of myContracts) {
+    const artifactDir = join(specBase, '.runtime', 'contract-artifacts', contract.provider)
+    const artifactFile = join(artifactDir, 'endpoints.json')
+
+    let endpoints = []
+    if (existsSync(artifactFile)) {
+      try {
+        const artifact = JSON.parse(readFileSync(artifactFile, 'utf8'))
+        endpoints = artifact.endpoints || []
+      } catch {}
+    }
+
+    parts.push(`### Upstream Contract: ${contract.provider}`)
+    if (endpoints.length > 0) {
+      parts.push(`\nAvailable endpoints from **${contract.provider}**:`)
+      for (const ep of endpoints) {
+        parts.push(`- **${ep.method}** \`${ep.path}\``)
+      }
+    } else {
+      parts.push(`\n⚠️ No endpoint artifact found for ${contract.provider}. This may indicate a contract gap.`)
+    }
+  }
+
+  if (parts.length === 0) return null
+
+  parts.unshift('## Upstream API Contracts')
+  parts.push('')
+  parts.push('### Rules')
+  parts.push('1. Do not invent API paths. Use only endpoints listed above.')
+  parts.push('2. If a required endpoint is missing, **stop and report the contract gap** instead of coding around it.')
+  parts.push('3. If you need to add new endpoints, you must also update the backend provider task.')
+
+  return parts.join('\n')
+}
+
+// ─── Verify 阶段：parity check ──────────────────────────────────────────
+
+/**
+ * verify 阶段执行 API parity check
+ * @param {string} specBase - .sillyspec 目录
+ * @param {string} worktreePath - worktree 路径
+ * @returns {{ ok: boolean, missingBackend: Array, unusedBackend: Array, summary: string }}
+ */
+export function verifyApiParity(specBase, worktreePath) {
+  const { diffApiParity } = require('./endpoint-extractor.js')
+
+  // 读取所有 provider artifacts
+  const artifactBase = join(specBase, '.runtime', 'contract-artifacts')
+  const allProviderEndpoints = []
+
+  if (existsSync(artifactBase)) {
+    for (const entry of readdirSync(artifactBase, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue
+      const epFile = join(artifactBase, entry.name, 'endpoints.json')
+      if (existsSync(epFile)) {
+        try {
+          const artifact = JSON.parse(readFileSync(epFile, 'utf8'))
+          for (const ep of (artifact.endpoints || [])) {
+            allProviderEndpoints.push({
+              method: ep.method,
+              path: ep.path,
+              source: `${entry.name}/${ep.source}`,
+            })
+          }
+        } catch {}
+      }
+    }
+  }
+
+  // 扫描前端调用
+  if (!worktreePath || !existsSync(worktreePath)) {
+    return {
+      ok: true,
+      missingBackend: [],
+      unusedBackend: [],
+      summary: 'No worktree to scan for parity check',
+    }
+  }
+
+  const frontendCalls = scanFrontendApiCalls(worktreePath)
+  const { missingBackend, unusedBackend } = diffApiParity(frontendCalls, allProviderEndpoints)
+
+  const ok = missingBackend.length === 0
+  let summary = ok
+    ? `✅ API parity check passed: ${allProviderEndpoints.length} backend endpoints, ${frontendCalls.length} frontend calls`
+    : `❌ API parity check failed: ${missingBackend.length} frontend calls have no matching backend endpoint`
+
+  if (unusedBackend.length > 0) {
+    summary += ` | ${unusedBackend.length} backend endpoints unused by frontend`
+  }
+
+  return { ok, missingBackend, unusedBackend, summary }
+}