sillyspec 3.22.8 → 3.23.0

package/package.json

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

package/src/hooks/worktree-guard.js

@@ -9,7 +9,7 @@
  * - 拦截提示针对每个阶段给出具体修复建议
  */
 
-import { existsSync, readFileSync } from 'fs'
+import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
 
 // ── 常量 ──
@@ -555,6 +555,72 @@ function buildStageHint(stage) {
   return hint.join('\n')
 }
 
+/**
+ * 读取并合并所有活跃 quick session 的 guard（D-002@v1）
+ *
+ * 为什么合并而不是读单个 session：
+ * - hook 是独立进程（agent 写文件时触发，非 quick CLI），无法可靠知道当前 agent 属于哪个 quick session。
+ * - `current-quick-run-id` 是单文件多会话覆盖，读到的可能是他者 session。
+ * - 对策：读所有活跃 quick-sessions 下各 session 的 guard.json，合并 baselineFiles / allowedFiles 并集。
+ *   多会话时保护范围过宽（保护所有 session 的 baseline），但不误拦任何 session 的合法写——安全侧倾斜。
+ *
+ * 兼容：旧版单文件 `.runtime/quick-guard.json`（task-03 前格式，无 session 目录）也并入合并。
+ *
+ * @param {string} projectRoot
+ * @returns {{ baselineFiles: string[], allowedFiles: string[], hasGuard: boolean }}
+ *   - baselineFiles/allowedFiles 为所有活跃 session 的并集（去重，保持首次出现顺序）
+ *   - hasGuard 表示是否存在任何 guard（用于区分"无 quick 任务"与"有 guard 但列表为空"）
+ */
+function readAllQuickGuards(projectRoot) {
+  const baselineSet = new Set()
+  const allowedSet = new Set()
+  let hasGuard = false
+
+  const sessionsDir = path.join(projectRoot, '.sillyspec', '.runtime', 'quick-sessions')
+  let sessionDirs = []
+  try {
+    const entries = readdirSync(sessionsDir, { withFileTypes: true })
+    sessionDirs = entries.filter(e => e.isDirectory()).map(e => e.name)
+  } catch { /* 目录不存在或不可读 → 无活跃 session */ }
+
+  for (const sessionName of sessionDirs) {
+    const guardFile = path.join(sessionsDir, sessionName, 'guard.json')
+    if (!existsSync(guardFile)) continue
+    let guard
+    try {
+      guard = JSON.parse(readFileSync(guardFile, 'utf8'))
+    } catch { continue } // 损坏的 guard.json 跳过（不污染并集）
+    hasGuard = true
+    for (const f of Array.isArray(guard.baselineFiles) ? guard.baselineFiles : []) {
+      if (typeof f === 'string' && f) baselineSet.add(f)
+    }
+    for (const f of Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []) {
+      if (typeof f === 'string' && f) allowedSet.add(f)
+    }
+  }
+
+  // 兼容：旧版单文件 quick-guard.json（task-03 前格式，迁移期残留）
+  const legacyGuardFile = path.join(projectRoot, '.sillyspec', '.runtime', 'quick-guard.json')
+  if (existsSync(legacyGuardFile)) {
+    try {
+      const guard = JSON.parse(readFileSync(legacyGuardFile, 'utf8'))
+      hasGuard = true
+      for (const f of Array.isArray(guard.baselineFiles) ? guard.baselineFiles : []) {
+        if (typeof f === 'string' && f) baselineSet.add(f)
+      }
+      for (const f of Array.isArray(guard.allowedFiles) ? guard.allowedFiles : []) {
+        if (typeof f === 'string' && f) allowedSet.add(f)
+      }
+    } catch { /* 旧文件损坏，忽略 */ }
+  }
+
+  return {
+    baselineFiles: [...baselineSet],
+    allowedFiles: [...allowedSet],
+    hasGuard,
+  }
+}
+
 // ── 公共接口 ──
 
 /**
@@ -595,26 +661,20 @@ export function shouldBlockWrite(filePath, cwd) {
     }
   }
 
-  // quick 阶段：检查 quick-guard.json 的 baselineFiles
+  // quick 阶段：检查 baselineFiles（合并所有活跃 session guard 并集，D-002@v1）
   if (stage === 'quick') {
-    try {
-      const guardFile = path.join(projectRoot, '.sillyspec', '.runtime', 'quick-guard.json')
-      const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
-      const baselineFiles = guard.baselineFiles || []
-      const relTarget = path.relative(projectRoot, absPath)
-      // 如果目标是 baseline protected file，阻止写入
-      if (baselineFiles.some(f => relTarget === f || relTarget.startsWith(f + path.sep))) {
-        return {
-          blocked: true,
-          reason: [
-            `⚠️ quick 变更边界保护：${relTarget} 是 baseline 文件，不允许覆盖。`,
-            `当前 quick 任务不能修改任务开始前已修改的文件。`,
-            `如确需修改，请在 quick 完成后单独处理此文件。`,
-          ].join('\n')
-        }
+    const { baselineFiles } = readAllQuickGuards(projectRoot)
+    const relTarget = path.relative(projectRoot, absPath)
+    // 如果目标是 baseline protected file，阻止写入（并集 = 保护所有 session 的 baseline）
+    if (baselineFiles.some(f => relTarget === f || relTarget.startsWith(f + path.sep))) {
+      return {
+        blocked: true,
+        reason: [
+          `⚠️ quick 变更边界保护：${relTarget} 是 baseline 文件，不允许覆盖。`,
+          `当前 quick 任务不能修改任务开始前已修改的文件。`,
+          `如确需修改，请在 quick 完成后单独处理此文件。`,
+        ].join('\n')
       }
-    } catch {
-      // quick-guard.json 不存在（非 quick 任务或未记录），放行
     }
     return { blocked: false }
   }
@@ -679,24 +739,19 @@ export function shouldBlockBash(command, cwd) {
     }
   }
 
-  // quick 阶段：检查 quick-guard.json
+  // quick 阶段：检查合并后的 baselineFiles（所有活跃 session guard 并集，D-002@v1）
   if (stage === 'quick') {
     // 危险黑名单仍然拦截
     if (matchDangerBlacklist(command)) {
       return { blocked: true, reason: `dangerous command blocked: ${command.trim()}` }
     }
-    // 检查命令是否会覆盖 baseline files
-    try {
-      const guardFile = path.join(projectRoot, '.sillyspec', '.runtime', 'quick-guard.json')
-      const guard = JSON.parse(readFileSync(guardFile, 'utf8'))
-      const baselineFiles = guard.baselineFiles || []
-      // 检查命令中是否引用了 baseline file
-      for (const f of baselineFiles) {
-        if (command.includes(f) && (command.includes('> ') || command.includes(' tee ') || command.includes('sed ') || command.includes('mv '))) {
-          return { blocked: true, reason: `quick 变更边界保护：命令可能覆盖 baseline 文件 ${f}` }
-        }
+    // 检查命令是否会覆盖 baseline files（并集 = 保护所有 session 的 baseline）
+    const { baselineFiles } = readAllQuickGuards(projectRoot)
+    for (const f of baselineFiles) {
+      if (command.includes(f) && (command.includes('> ') || command.includes(' tee ') || command.includes('sed ') || command.includes('mv '))) {
+        return { blocked: true, reason: `quick 变更边界保护：命令可能覆盖 baseline 文件 ${f}` }
       }
-    } catch {}
+    }
     return { blocked: false }
   }
 

package/src/index.js

@@ -6,10 +6,11 @@
  * 只负责两件事：init（安装命令模板）和 setup（安装 MCP 工具）。
  * 状态管理通过 sillyspec.db（SQLite）完成，使用 `sillyspec progress` 命令。
  */
-import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { cmdInit, getVersion } from './init.js';
 import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
+import { detectLocalYaml } from './local-detect.js';
 
 // ── CLI 入口 ──
 
@@ -57,7 +58,7 @@ SillySpec CLI — 规范驱动开发工具包
 
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）
     init | show | set-stage <stage> | add-step <stage> <name> |
-    update-step <stage> <name> --status <st> [--output <t>] | complete-stage <stage> |
+    update-step <stage> <name> --status <st> [--output <t>] [--force] | complete-stage <stage> [--force] |
     check | repair [--apply] | validate | reset [--stage X] |
     batch --total N --completed M [--failed F] [--skipped K] | batch --status
 
@@ -69,8 +70,12 @@ SillySpec CLI — 规范驱动开发工具包
     cleanup <change> [--force]          清理 worktree
     doctor [--fix] [--stale-hours N]    健康检查 + 修复
 
+  sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
+
   sillyspec workflow check <name> [--project <p>] [--change <c>] [--json]
   sillyspec workflow list
+  sillyspec gate <stage> --change <name> [--json]      机器门控：阶段能否标记完成（只读）
+  sillyspec derive <facet> --change <name> [--json]    单项事实核验（facet: execute-evidence|verify-test|task-reviews|artifacts）
   sillyspec modules <rebuild | status | migrate>
   sillyspec change-rename <旧变更名> <新变更名>
   sillyspec knowledge <search --query "..." --limit N
@@ -106,6 +111,23 @@ SillySpec CLI — 规范驱动开发工具包
 `);
 }
 
+// --json 模式输出纪律（design §8 风险表）：machine-interface 的 runGate/runDerive 执行期间，
+// 被调模块（validators/task-review/verify-postcheck）的人类可读 console.log 会污染 stdout 破坏 JSON。
+// 在整个调用期间把 console.log/info 重定向到 stderr，stdout 留给最终 JSON envelope（D-005@v1）。
+async function withJsonOutput(json, fn) {
+  if (!json) return fn();
+  const origLog = console.log;
+  const origInfo = console.info;
+  console.log = (...a) => process.stderr.write(a.map(String).join(' ') + '\n');
+  console.info = (...a) => process.stderr.write(a.map(String).join(' ') + '\n');
+  try {
+    return await fn();
+  } finally {
+    console.log = origLog;
+    console.info = origInfo;
+  }
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -246,13 +268,14 @@ async function main() {
             if (args[ai] === '--status' && args[ai + 1]) { updStatus = args[ai + 1]; ai++; }
             if (args[ai] === '--output' && args[ai + 1]) { updOutput = args[ai + 1]; ai++; }
           }
-          pm.updateStep(dir, updStepStage, updStepName, { status: updStatus, output: updOutput }, progChangeName);
+          const updForce = args.includes('--force');
+          await pm.updateStep(dir, updStepStage, updStepName, { status: updStatus, output: updOutput, force: updForce }, progChangeName);
           break;
         }
         case 'complete-stage': {
           const compStageName = filteredArgs[2];
-          if (!compStageName) { console.log('❌ 用法: sillyspec progress complete-stage <stage>'); break; }
-          pm.completeStage(dir, compStageName, progChangeName);
+          if (!compStageName) { console.log('❌ 用法: sillyspec progress complete-stage <stage> [--force]'); break; }
+          await pm.completeStage(dir, compStageName, progChangeName, { force: args.includes('--force') });
           break;
         }
         case 'batch': {
@@ -286,6 +309,70 @@ async function main() {
       }
       break;
     }
+    case 'gate': {
+      // 机器门控（machine-interface v1）：聚合「变更的 <stage> 阶段此刻能否标记完成」的综合结论。
+      // 只读查询，不依赖 worktree、不写状态（D-002@v1）。
+      const gateStage = filteredArgs[1];
+      const gateChangeIdx = args.indexOf('--change');
+      const gateChange = gateChangeIdx >= 0 && args[gateChangeIdx + 1] ? args[gateChangeIdx + 1] : null;
+      if (!gateStage || gateStage.startsWith('-') || !gateChange) {
+        console.error('用法: sillyspec gate <stage> --change <name> [--json]\n  stage: brainstorm | plan | execute | verify | archive | ...');
+        process.exit(2);
+      }
+      const { runGate } = await import('./machine-interface.js');
+      // --spec-dir 透传 runGate.specBase（gate CLI 接线修复，P3 坑 3 sillyspec 侧）。
+      // runGate 已分离 cwd(跑测试) + specBase(读 local.yaml/spec)，但 gate case 之前
+      // 只传 cwd 致 --spec-dir 对 gate verify 无效。不传 --spec-dir 时 specBase 走默认
+      // resolveSpecDir(cwd)，向后兼容。
+      const gateOpts = { cwd: dir };
+      if (specDir) gateOpts.specBase = specDir;
+      const { envelope, exitCode } = await withJsonOutput(json, () => runGate(gateStage, gateChange, gateOpts));
+      if (json) {
+        process.stdout.write(JSON.stringify(envelope));
+      } else {
+        const icon = envelope.ok ? '✅' : '❌';
+        console.log(`${icon} gate ${gateStage} [${gateChange}]: ${envelope.ok ? '通过' : '未通过'} (exit ${exitCode})`);
+        for (const c of (envelope.checks || [])) {
+          const ci = c.ok ? '✅' : '❌';
+          const tag = c.informational ? ' (informational)' : '';
+          console.log(`  ${ci} ${c.id}${tag}`);
+          for (const e of (c.errors || [])) console.log(`     ✗ ${e}`);
+          for (const w of (c.warnings || [])) console.log(`     ⚠ ${w}`);
+        }
+        for (const e of (envelope.errors || [])) console.log(`  ✗ ${e}`);
+        for (const w of (envelope.warnings || [])) console.log(`  ⚠ ${w}`);
+      }
+      process.exitCode = exitCode;
+      break;
+    }
+    case 'derive': {
+      // 单项事实核验（machine-interface v1）：查询变更某一 facet 的真实状态，返回结构化 data。
+      const facet = filteredArgs[1];
+      const deriveChangeIdx = args.indexOf('--change');
+      const deriveChange = deriveChangeIdx >= 0 && args[deriveChangeIdx + 1] ? args[deriveChangeIdx + 1] : null;
+      if (!facet || facet.startsWith('-') || !deriveChange) {
+        console.error('用法: sillyspec derive <facet> --change <name> [--json]\n  facet: execute-evidence | verify-test | task-reviews | artifacts');
+        process.exit(2);
+      }
+      const { runDerive } = await import('./machine-interface.js');
+      // --spec-dir 透传 runDerive.specBase（与 gate case 对称，P3 坑 3 sillyspec 侧）。
+      // derive verify-test facet 内部同样调 runVerifyTestCheck 依赖 specBase，平台模式
+      // 下需透传；不传 --spec-dir 时走默认 resolveSpecDir(cwd)，向后兼容。
+      const deriveOpts = { cwd: dir };
+      if (specDir) deriveOpts.specBase = specDir;
+      const { envelope, exitCode } = await withJsonOutput(json, () => runDerive(facet, deriveChange, deriveOpts));
+      if (json) {
+        process.stdout.write(JSON.stringify(envelope));
+      } else {
+        const icon = envelope.ok ? '✅' : '❌';
+        console.log(`${icon} derive ${facet} [${deriveChange}]: ${envelope.ok ? '通过' : '未通过'} (exit ${exitCode})`);
+        if (envelope.data) console.log(`  data: ${JSON.stringify(envelope.data, null, 2)}`);
+        for (const e of (envelope.errors || [])) console.log(`  ✗ ${e}`);
+        for (const w of (envelope.warnings || [])) console.log(`  ⚠ ${w}`);
+      }
+      process.exitCode = exitCode;
+      break;
+    }
     case 'docs': {
       const docsSubCmd = filteredArgs[1];
       if (docsSubCmd === 'migrate') {
@@ -1041,6 +1128,55 @@ SillySpec modules — 模块文档管理
       }
       break;
     }
+    case 'local': {
+      // 本地配置探测（task-04 / D-001@v1）：纯 fs 嗅探项目类型 → 生成 local.yaml。
+      // 轻量独立路由，不跑 scan、不消耗 token。探测逻辑归属 local-detect.js（task-02）。
+      const localSubCmd = filteredArgs[1];
+      if (localSubCmd !== 'detect') {
+        console.error('用法: sillyspec local detect [--dir <path>]\n  纯 fs 嗅探项目类型并生成 local.yaml（不跑 scan、零 token）');
+        process.exit(2);
+      }
+
+      const detected = detectLocalYaml(dir);
+      const specRoot = resolvePlatformSpecDir(dir, specDir) || join(dir, '.sillyspec');
+      const localYamlPath = join(specRoot, 'local.yaml');
+
+      if (existsSync(localYamlPath)) {
+        console.log(`ℹ️  local.yaml 已存在，跳过: ${localYamlPath}`);
+        break;
+      }
+
+      // 序列化为 local.yaml 文本（与 scan.js 生成本地配置步骤的 yaml 模板格式一致，向后兼容）
+      const c = detected.commands || {};
+      const lines = [];
+      lines.push('# SillySpec 本地配置（自动生成，可手动修改）');
+      lines.push('project:');
+      lines.push(`  type: ${detected.project.type}  # nodejs/maven/gradle/make/generic`);
+      lines.push('');
+      lines.push('commands:');
+      if (c.build) lines.push(`  build: "${c.build}"`);
+      if (c.test) lines.push(`  test: "${c.test}"`);
+      if (c.lint) lines.push(`  lint: "${c.lint}"`);
+      lines.push('');
+      lines.push('# 测试策略：full=全量测试, module=只测变更模块, skip=跳过测试');
+      lines.push('test_strategy: module');
+      lines.push('');
+      lines.push('# 模块测试路径映射（可选）');
+      lines.push('# module_paths:');
+      lines.push('#   user-service: "user/"');
+      lines.push('#   order-service: "order/"');
+      const yamlText = lines.join('\n') + '\n';
+
+      // 原子写：mkdir -p specRoot → 写 tmp → rename
+      mkdirSync(specRoot, { recursive: true });
+      const tmpPath = localYamlPath + '.tmp';
+      writeFileSync(tmpPath, yamlText, 'utf8');
+      renameSync(tmpPath, localYamlPath);
+
+      console.log(`✅ 已生成 local.yaml (type: ${detected.project.type})`);
+      console.log(`   路径: ${localYamlPath}`);
+      break;
+    }
     default:
       console.error(`❌ 未知命令: ${command}`);
       printUsage();

package/src/local-detect.js

@@ -0,0 +1,110 @@
+/**
+ * Local Detect — 纯 fs 项目类型嗅探
+ *
+ * 把"生成本地配置"里的项目类型判定从 scan（半小时 + 大量 token）抽出来，
+ * 变成纯 fs 同步读几秒可完成的独立探测。create/gate 只需 project.type +
+ * commands，不该被迫跑完整 scan。
+ *
+ * 纯函数：不 spawn 任何子进程、不调用任何 AI/LLM、不消耗 token。
+ * 不写 local.yaml 到磁盘——只返回数据结构，落盘由调用方（CLI 路由 / scan.js）负责。
+ * 不引 yaml 依赖。
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+
+/**
+ * 从 Makefile 文本提取 test 目标的命令（轻量正则，与 verify-postcheck 同风格）。
+ * 支持两种常见写法：
+ *   - 同行命令：`test: pytest`            → 'pytest'
+ *   - tab 续行：`test:\n\tpytest\n`        → 'pytest'（命令在下一 tab 开头行）
+ * 边界：
+ *   - 纯空目标（`test:` 无同行命令、无 tab 续行）→ 回退 'make test'
+ *   - 命令行内 `#` 注释截断；取第一个非空命令行
+ * @param {string} makefileText
+ * @returns {string}
+ */
+function parseMakefileTestCommand(makefileText) {
+  if (!makefileText) return 'make test'
+  // 定位 `test:` 行；捕获 `:` 后同行内容（同行命令或空）
+  const head = makefileText.match(/^test:\s*([^\n#]*?)\s*(?:#.*)?$/m)
+  if (!head) return 'make test'
+  const inline = (head[1] || '').trim()
+  if (inline) return inline
+  // 同行为空 → 找该行之后第一个 tab 续行命令（`\tcmd` 或 `    cmd`）
+  const after = makefileText.slice(head.index + head[0].length)
+  const cont = after.match(/^[ \t]+([^\n#]+?)\s*(?:#.*)?$/m)
+  if (cont && cont[1]) return cont[1].trim()
+  return 'make test'
+}
+
+/**
+ * 嗅探 workdir 的项目类型与默认 commands（纯 fs，零 AI / 零 token）。
+ *
+ * 嗅探规则（按顺序，命中即返回）：
+ *   - package.json → nodejs（npm run build / npm test / npm run lint）
+ *   - pom.xml → maven（mvn compile / mvn test / mvn checkstyle:check）
+ *   - build.gradle → gradle（./gradlew build / test / check）
+ *   - Makefile → make（test 命令从 test: 目标解析；build/lint 无则不写）
+ *   - 都没有 → generic（commands 为空对象）
+ *
+ * @param {string} workdir - 项目根目录
+ * @returns {{
+ *   project: { type: 'nodejs'|'maven'|'gradle'|'make'|'generic' },
+ *   commands: { build?: string, test?: string, lint?: string }
+ * }}
+ */
+export function detectLocalYaml(workdir) {
+  // 1. nodejs
+  if (existsSync(join(workdir, 'package.json'))) {
+    return {
+      project: { type: 'nodejs' },
+      commands: {
+        build: 'npm run build',
+        test: 'npm test',
+        lint: 'npm run lint',
+      },
+    }
+  }
+
+  // 2. maven
+  if (existsSync(join(workdir, 'pom.xml'))) {
+    return {
+      project: { type: 'maven' },
+      commands: {
+        build: 'mvn compile',
+        test: 'mvn test',
+        lint: 'mvn checkstyle:check',
+      },
+    }
+  }
+
+  // 3. gradle
+  if (existsSync(join(workdir, 'build.gradle'))) {
+    return {
+      project: { type: 'gradle' },
+      commands: {
+        build: './gradlew build',
+        test: './gradlew test',
+        lint: './gradlew check',
+      },
+    }
+  }
+
+  // 4. make（test 命令从 Makefile 解析；build/lint 无则省略）
+  const makefilePath = join(workdir, 'Makefile')
+  if (existsSync(makefilePath)) {
+    const makefileText = readFileSync(makefilePath, 'utf8')
+    const test = parseMakefileTestCommand(makefileText)
+    return {
+      project: { type: 'make' },
+      commands: { test },
+    }
+  }
+
+  // 5. generic
+  return {
+    project: { type: 'generic' },
+    commands: {},
+  }
+}