sillyspec 3.15.2 → 3.16.1

package/src/workflow.js

@@ -630,8 +630,12 @@ export function generateAllRolePrompts(wf, projectName, context = {}) {
  * @returns {string|null} 保存路径，失败返回 null
  */
 export function saveWorkflowRun(result, options = {}) {
-  const { cwd = '.', source = 'unknown', stage, step } = options
-  const runDir = join(cwd, '.sillyspec', '.runtime', 'workflow-runs')
+  const { cwd = '.', source = 'unknown', stage, step, runtimeRoot, scanRunId } = options
+  // 平台模式：写入 runtime-root/scan-runs/<scan-run-id>/workflow-runs/
+  // 本地模式：写入 cwd/.sillyspec/.runtime/workflow-runs/
+  const runDir = runtimeRoot
+    ? join(runtimeRoot, 'scan-runs', scanRunId || 'unknown', 'workflow-runs')
+    : join(cwd, '.sillyspec', '.runtime', 'workflow-runs')
   try {
     mkdirSync(runDir, { recursive: true })
   } catch (e) {

package/src/worktree-apply.js

@@ -341,10 +341,24 @@ export function formatExecuteSummary({ changeName, stepsCompleted, stepsTotal, a
       ? `dirty (${baselineCount} baseline file${baselineCount === 1 ? '' : 's'} protected)`
       : 'clean';
 
+    // Worktree 最终状态
+    const mode = meta.mode || 'worktree';
+    let worktreeStatus;
+    if (mode === 'native-worktree') {
+      worktreeStatus = 'kept (external worktree)';
+    } else if (mode === 'in-place-fallback') {
+      worktreeStatus = 'none (in-place)';
+    } else if (!wtExists) {
+      worktreeStatus = 'cleaned';
+    } else {
+      worktreeStatus = 'exists';
+    }
+
     lines.push(`Status:     COMPLETED`);
     lines.push(`Steps:      ${stepsCompleted} / ${stepsTotal}`);
     lines.push(`Baseline:   ${baselineStatus}`);
     lines.push(`Apply:      ${applyStatus}`);
+    lines.push(`Worktree:   ${worktreeStatus}`);
   }
 
   // --- Changed files ---

package/src/worktree.js

@@ -17,6 +17,45 @@ const WORKTREES_REL = '.sillyspec/.runtime/worktrees';
 const BRANCH_PREFIX = 'sillyspec/';
 const META_FILE = 'meta.json';
 
+/**
+ * 检测当前目录的隔离状态
+ * 返回 { inWorktree: boolean, inSubmodule: boolean }
+ *
+ * 用 git rev-parse --git-dir 和 --git-common-dir 判断：
+ * - GIT_DIR != GIT_COMMON 通常是 linked worktree
+ * - 但在 git submodule 里也会出现这种情况
+ * - 所以必须额外检查 --show-superproject-working-tree 排除 submodule
+ */
+export function detectIsolation(cwd = process.cwd()) {
+  try {
+    const gitDir = execSync('git rev-parse --git-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    const gitCommonDir = execSync('git rev-parse --git-common-dir', { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+    const superProject = gitQuiet(cwd, 'rev-parse --show-superproject-working-tree');
+
+    const inWorktree = gitDir !== gitCommonDir && !superProject;
+    const inSubmodule = !!superProject;
+
+    return { inWorktree, inSubmodule, gitDir, gitCommonDir };
+  } catch {
+    return { inWorktree: false, inSubmodule: false, gitDir: null, gitCommonDir: null };
+  }
+}
+
+/**
+ * 检查 worktree 存储目录是否被 .gitignore 忽略
+ * @param {string} cwd - 项目根目录
+ * @returns {{ ignored: boolean, path: string }}
+ */
+export function checkWorktreeDirIgnored(cwd = process.cwd()) {
+  const relPath = WORKTREES_REL;
+  try {
+    execSync(`git check-ignore -q ${relPath}`, { cwd, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] });
+    return { ignored: true, path: relPath };
+  } catch {
+    return { ignored: false, path: relPath };
+  }
+}
+
 function git(cwd, args) {
   return execSync(`git ${args}`, { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
 }
@@ -115,7 +154,37 @@ export class WorktreeManager {
     const worktreePath = this.getWorktreePath(name);
     const branch = BRANCH_PREFIX + name;
 
-    // 1. 检查 worktree 是否已存在
+    // 0. 检测当前环境隔离状态（submodule guard）
+    const isolation = detectIsolation(this.cwd);
+    if (isolation.inSubmodule) {
+      throw new Error(
+        '当前目录在 git submodule 内，SillySpec worktree 不支持在 submodule 中创建。' +
+        '\n请在主仓库中执行，或使用 --no-worktree 跳过隔离。'
+      );
+    }
+    if (isolation.inWorktree) {
+      // 已在 linked worktree 中，复用当前目录作为 worktree 路径
+      console.log(`ℹ️  已在 linked worktree 中（git-dir: ${isolation.gitDir}），复用当前隔离环境。`);
+      return this._createInPlaceMeta(name, {
+        worktreePath: this.cwd,
+        branch: gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || 'detached',
+        mode: 'native-worktree',
+        base,
+      });
+    }
+
+    // 1. 检查 worktree 目录是否被 gitignore
+    const ignoreStatus = checkWorktreeDirIgnored(this.cwd);
+    if (!ignoreStatus.ignored) {
+      throw new Error(
+        `worktree 存储目录 ${ignoreStatus.path} 未被 .gitignore 忽略，` +
+        `创建 worktree 可能导致内容被误提交。\n` +
+        `请先在 .gitignore 中添加: ${ignoreStatus.path}/\n` +
+        `或运行 sillyspec doctor 检查修复。`
+      );
+    }
+
+    // 2. 检查 worktree 是否已存在
     if (existsSync(worktreePath)) {
       // 目录在但 meta.json 不存在（幽灵状态），自动清理
       if (!this.getMeta(name)) {
@@ -147,7 +216,7 @@ export class WorktreeManager {
       mkdirSync(this.worktreeBase, { recursive: true });
     }
 
-    // 5. 创建 worktree（含版本检测）
+    // 5. 创建 worktree（含版本检测 + sandbox fallback）
     try {
       git(this.cwd, `worktree add ${worktreePath} -b ${branch} ${baseHash}`);
     } catch (e) {
@@ -155,7 +224,16 @@ export class WorktreeManager {
       if (!check.supported) {
         throw new Error(`git worktree add 失败: ${e.stderr || e.message}\n\n${check.reason ? `原因: ${check.reason}` : ''}\n建议: 使用 --no-worktree 标志跳过隔离，或升级 git 到 >= 2.15`);
       }
-      throw new Error(`git worktree add 失败: ${e.stderr || e.message}`);
+      // sandbox/permission fallback: 降级为 in-place + baseline protection
+      console.log(`⚠️  git worktree add 失败（可能是沙箱权限限制），降级为 in-place 模式 + baseline protection`);
+      console.log(`   原因: ${e.stderr || e.message}`);
+      return this._createInPlaceMeta(name, {
+        worktreePath: this.cwd,
+        branch,
+        baseBranch,
+        baseHash,
+        mode: 'in-place-fallback',
+      });
     }
 
     // 5.5 自动同步远程最新代码（防止 worktree 基于过时的 commit）
@@ -206,15 +284,99 @@ export class WorktreeManager {
       actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
       createdAt: new Date().toISOString(),
       worktreePath,
+      mode: 'worktree',
       baselineFiles,
       baselineCommit,
-      baselineHash,  // 有 dirty baseline 时指向 checkpoint commit
+      baselineHash,
     };
 
     const metaPath = join(worktreePath, META_FILE);
     writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
 
-    return { branch, worktreePath, baseHash };
+    return { branch, worktreePath, baseHash, mode: meta.mode };
+  }
+
+  /**
+   * 创建 in-place 模式的 meta.json（降级路径）
+   * 不创建 git worktree，直接在当前目录记录 baseline 并写入 meta
+   * @private
+   */
+  _createInPlaceMeta(name, { worktreePath, branch, baseBranch, baseHash, mode } = {}) {
+    // 解析 base
+    if (!baseHash) {
+      baseBranch = baseBranch || gitQuiet(this.cwd, 'symbolic-ref --short HEAD') || gitQuiet(this.cwd, 'rev-parse HEAD');
+      baseHash = git(this.cwd, 'rev-parse HEAD');
+    }
+
+    const baselineResult = this._overlayBaseline(this.cwd, this.cwd);
+    const baselineFiles = baselineResult.files;
+    const baselineHash = baselineResult.baselineHash;
+
+    let baselineCommit = null;
+    if (baselineFiles.length > 0) {
+      baselineCommit = this._createBaselineCheckpoint(this.cwd, name);
+    }
+
+    const meta = {
+      changeName: name,
+      branch: branch || BRANCH_PREFIX + name,
+      baseBranch,
+      baseHash,
+      actualBaseHash: gitQuiet(worktreePath, 'rev-parse HEAD') || baseHash,
+      createdAt: new Date().toISOString(),
+      worktreePath,
+      mode: mode || 'in-place-fallback',
+      baselineFiles,
+      baselineCommit,
+      baselineHash,
+    };
+
+    // in-place 模式下 meta 写入 worktreeBase（避免污染主工作区）
+    if (!existsSync(this.worktreeBase)) {
+      mkdirSync(this.worktreeBase, { recursive: true });
+    }
+    const metaPath = join(this.worktreeBase, name, META_FILE);
+    const metaDir = join(this.worktreeBase, name);
+    if (!existsSync(metaDir)) {
+      mkdirSync(metaDir, { recursive: true });
+    }
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+    return { branch: meta.branch, worktreePath, baseHash, mode: meta.mode };
+  }
+
+  /**
+   * 构建 isolation 信息对象，用于写入 gate-status.json
+   * @param {string} changeName
+   * @returns {{ status: string, mode: string, path: string } | null}
+   */
+  getIsolationInfo(changeName) {
+    const meta = this.getMeta(changeName);
+    if (!meta) return null;
+
+    const mode = meta.mode || 'worktree';
+    const statusMap = {
+      'worktree': 'verified',
+      'native-worktree': 'verified',
+      'in-place-fallback': 'degraded',
+    };
+
+    return {
+      status: statusMap[mode] || 'verified',
+      mode,
+      path: meta.worktreePath,
+      branch: meta.branch,
+    };
+  }
+
+  /**
+   * 获取 worktree 的运行模式
+   * @param {string} changeName
+   * @returns {'worktree'|'native-worktree'|'in-place-fallback'|null}
+   */
+  getMode(changeName) {
+    const meta = this.getMeta(changeName);
+    return meta?.mode || null;
   }
 
   /**
@@ -239,6 +401,7 @@ export class WorktreeManager {
         baseBranch: meta.baseBranch,
         createdAt: meta.createdAt,
         worktreePath: meta.worktreePath,
+        mode: meta.mode || 'worktree',
       });
     }
 
@@ -246,24 +409,43 @@ export class WorktreeManager {
   }
 
   /**
-   * 清理 worktree（强制删除，不 apply）
+   * 清理 worktree（仅限 SillySpec 创建的临时 worktree）
    * @param {string} changeName
-   * @throws {Error} worktree 不存在
+   * @param {{ force?: boolean }} opts - force: 跳过 mode 安检（仅用于 worktree 目录本身）
+   * @throws {Error} worktree 不存在、不允许删除
+   * @returns {{ result: 'cleaned'|'skipped'|'kept', mode: string }}
    */
-  cleanup(changeName) {
+  cleanup(changeName, { force = false } = {}) {
     const name = validateChangeName(changeName);
     const meta = this.getMeta(name);
     const worktreePath = this.getWorktreePath(name);
 
     if (!meta && !existsSync(worktreePath)) {
-      throw new Error(`worktree not found: ${name}。meta.json 不存在，目录也不存在，可能已被清理或从未创建。`);
+      return { result: 'skipped', mode: null };
+    }
+
+    const mode = meta?.mode || 'worktree';
+
+    // 安全检查：只有 SillySpec 创建的 worktree 才允许删除
+    if (!force) {
+      if (mode === 'native-worktree') {
+        throw new Error(
+          `当前 worktree 是外部/原生隔离环境（mode: native-worktree），SillySpec 不允许删除。\n` +
+          `此 worktree 不是由 SillySpec 创建的，请手动管理。\n` +
+          `如需强制清理，使用 --force 标志。`
+        );
+      }
+      if (mode === 'in-place-fallback') {
+        return { result: 'skipped', mode };
+      }
     }
 
     // 1. 尝试 git worktree remove
+    let gitRemoveOk = true;
     try {
       git(this.cwd, `worktree remove ${worktreePath} --force`);
-    } catch {
-      // git worktree remove 失败，尝试直接删除目录
+    } catch (e) {
+      gitRemoveOk = false;
     }
     const branch = (meta && meta.branch) || BRANCH_PREFIX + name;
 
@@ -283,6 +465,14 @@ export class WorktreeManager {
     if (existsSync(worktreePath)) {
       rmSync(worktreePath, { recursive: true, force: true });
     }
+
+    // 5. 清除 meta 目录（如果 worktree 目录在 worktreeBase 下）
+    const metaDir = join(this.worktreeBase, name);
+    if (existsSync(metaDir)) {
+      rmSync(metaDir, { recursive: true, force: true });
+    }
+
+    return { result: gitRemoveOk ? 'cleaned' : 'force-cleaned', mode };
   }
 
   /**

package/test/check-syntax.mjs

@@ -0,0 +1,26 @@
+import { execFileSync } from 'node:child_process'
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const roots = ['src']
+const files = []
+
+function walk(dir) {
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry)
+    const st = statSync(full)
+    if (st.isDirectory()) {
+      walk(full)
+      continue
+    }
+    if (/\.(js|cjs|mjs)$/.test(entry)) files.push(full)
+  }
+}
+
+for (const root of roots) walk(root)
+
+for (const file of files.sort()) {
+  execFileSync(process.execPath, ['--check', file], { stdio: 'inherit' })
+}
+
+console.log(`Checked ${files.length} JavaScript files`)

package/test/run-tests.mjs

@@ -0,0 +1,20 @@
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const testDir = dirname(fileURLToPath(import.meta.url))
+const files = readdirSync(testDir)
+  .filter(file => file.endsWith('.test.mjs'))
+  .sort()
+
+if (files.length === 0) {
+  console.log('No test files found')
+  process.exit(0)
+}
+
+for (const file of files) {
+  console.log(`\nRunning ${file}`)
+  await import(pathToFileURL(join(testDir, file)).href)
+}
+
+console.log(`\nAll ${files.length} test file(s) passed`)

package/test/scan-paths.test.mjs

@@ -0,0 +1,68 @@
+/**
+ * 防回归测试：scan.js 中不允许硬编码 .sillyspec/docs/<project>/ 作为写入路径
+ * 所有正式文档路径必须使用 {DOCS_ROOT} 占位符
+ */
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const scanPath = join(__dirname, '..', 'src', 'stages', 'scan.js')
+const content = readFileSync(scanPath, 'utf8')
+
+const banned = [
+  '.sillyspec/docs/<project>/scan/',
+  '.sillyspec/docs/<project>/modules/',
+  '.sillyspec/docs/<project>/flows/',
+  '.sillyspec/docs/<project>/glossary.md',
+]
+
+const required = [
+  '{DOCS_ROOT}/scan/',
+  '{DOCS_ROOT}/modules/',
+  '{DOCS_ROOT}/flows/',
+]
+
+let failed = false
+
+// 禁止硬编码路径
+for (const pattern of banned) {
+  if (content.includes(pattern)) {
+    console.error(`❌ FAIL: scan.js 仍包含硬编码路径 "${pattern}"`)
+    failed = true
+  } else {
+    console.log(`✅ PASS: 不包含 "${pattern}"`)
+  }
+}
+
+// 必须包含占位符
+for (const pattern of required) {
+  if (content.includes(pattern)) {
+    console.log(`✅ PASS: 包含占位符 "${pattern}"`)
+  } else {
+    console.error(`❌ FAIL: scan.js 缺少占位符 "${pattern}"`)
+    failed = true
+  }
+}
+
+// 禁止硬编码 projects 路径
+if (content.includes('.sillyspec/projects/')) {
+  console.error('❌ FAIL: scan.js 仍包含硬编码 ".sillyspec/projects/"')
+  failed = true
+} else {
+  console.log('✅ PASS: 不包含 ".sillyspec/projects/"')
+}
+
+if (content.includes('{PROJECTS_ROOT}/')) {
+  console.log('✅ PASS: 包含占位符 "{PROJECTS_ROOT}/"')
+} else {
+  console.error('❌ FAIL: scan.js 缺少占位符 "{PROJECTS_ROOT}/"')
+  failed = true
+}
+
+if (failed) {
+  console.error('\n💥 有测试失败！scan.js 路径占位符可能被回退为硬编码。')
+  process.exit(1)
+} else {
+  console.log('\n✅ 全部通过 — scan.js 路径占位符防回归测试 OK')
+}

package/test/stage-contract.test.mjs

@@ -0,0 +1,128 @@
+/**
+ * StageContract 状态转换 + validator 测试
+ */
+import { checkTransition, runValidators, getContract } from '../src/stage-contract.js'
+
+let failed = 0
+
+// === 状态转换测试 ===
+const transitionTests = [
+  // [from, to, expectedAllowed]
+  // 主流程正常顺序
+  ['', 'brainstorm', true],
+  ['brainstorm', 'plan', true],
+  ['plan', 'execute', true],
+  ['execute', 'verify', true],
+  ['verify', 'archive', true],
+
+  // 跳步应被拦截
+  ['', 'plan', false],
+  ['', 'execute', false],
+  ['brainstorm', 'execute', false],
+  ['plan', 'verify', false],
+  ['execute', 'archive', false],
+
+  // 回退应被拦截
+  ['plan', 'brainstorm', false],
+  ['execute', 'plan', false],
+  ['verify', 'execute', false],
+
+  // 辅助阶段随时可执行
+  ['', 'scan', true],
+  ['', 'quick', true],
+  ['', 'explore', true],
+  ['', 'doctor', true],
+  ['', 'archive', true],
+  ['brainstorm', 'scan', true],
+  ['plan', 'quick', true],
+  ['execute', 'doctor', true],
+
+  // 从辅助阶段进入主流程允许
+  ['scan', 'plan', true],
+  ['scan', 'brainstorm', true],
+  ['quick', 'plan', true],
+  ['doctor', 'brainstorm', true],
+
+  // archive 特殊：verify 后允许，其他主流程不允许直接跳
+  ['verify', 'archive', true],
+  ['execute', 'archive', false],
+  ['plan', 'archive', false],
+]
+
+console.log('=== 状态转换测试 ===')
+for (const [from, to, expected] of transitionTests) {
+  const r = checkTransition(from, to)
+  const ok = r.allowed === expected
+  if (!ok) failed++
+  console.log(ok ? '✅' : '❌', `${from || '(起始)'} → ${to}: allowed=${r.allowed} (exp ${expected})${ok ? '' : ' reason: ' + r.reason}`)
+}
+
+// === Validator 测试 ===
+console.log('\n=== Validator 测试 ===')
+
+// plan validator：plan.md 不存在应报错
+const planResult = runValidators('plan', '.', 'nonexistent-change')
+if (planResult.ok === false && planResult.errors.length > 0) {
+  console.log('✅ plan validator 检测到缺失 plan.md')
+} else {
+  console.log('❌ plan validator 未检测到缺失 plan.md')
+  failed++
+}
+
+// verify validator：变更目录不存在应报错
+const verifyResult = runValidators('verify', '.', 'nonexistent-change')
+if (verifyResult.ok === false && verifyResult.errors.length > 0) {
+  console.log('✅ verify validator 检测到缺失变更目录')
+} else {
+  console.log('❌ verify validator 未检测到缺失变更目录')
+  failed++
+}
+
+// scan validator：文档目录不存在应报错
+const scanResult = runValidators('scan', '/tmp/nonexistent-project', 'test', { projectName: 'test' })
+if (scanResult.ok === false && scanResult.errors.length > 0) {
+  console.log('✅ scan validator 检测到缺失 scan 文档')
+} else {
+  console.log('❌ scan validator 未检测到缺失 scan 文档')
+  failed++
+}
+
+// 无 validator 的阶段应该 pass
+const brainstormResult = runValidators('brainstorm', '.', 'test')
+if (brainstormResult.ok === true) {
+  console.log('✅ brainstorm 无 validator 直接通过')
+} else {
+  console.log('❌ brainstorm 无 validator 但失败了')
+  failed++
+}
+
+// === StageContract 结构测试 ===
+console.log('\n=== Contract 结构测试 ===')
+
+const plan = getContract('plan')
+if (plan.allowedFrom.includes('brainstorm') && plan.allowedTo.includes('execute') && plan.validators.length === 1) {
+  console.log('✅ plan contract 结构正确')
+} else {
+  console.log('❌ plan contract 结构异常:', JSON.stringify(plan))
+  failed++
+}
+
+const verify = getContract('verify')
+if (verify.allowedFrom.includes('execute') && verify.allowedTo.includes('archive')) {
+  console.log('✅ verify contract 结构正确')
+} else {
+  console.log('❌ verify contract 结构异常')
+  failed++
+}
+
+const unknown = getContract('nonexistent')
+if (unknown === null) {
+  console.log('✅ 未知阶段返回 null')
+} else {
+  console.log('❌ 未知阶段应返回 null')
+  failed++
+}
+
+// === 结果 ===
+console.log(`\n${failed === 0 ? '✅ 全部通过' : `❌ ${failed} 项失败`}`)
+process.exit(failed > 0 ? 1 : 0)

package/test/stage-definitions.test.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict'
+import { stageRegistry } from '../src/stages/index.js'
+import { buildPlanSteps } from '../src/stages/plan.js'
+import { buildExecuteSteps } from '../src/stages/execute.js'
+
+const stageSteps = {
+  brainstorm: stageRegistry.brainstorm.steps,
+  propose: stageRegistry.propose.steps,
+  scan: stageRegistry.scan.steps,
+  quick: stageRegistry.quick.steps,
+  archive: stageRegistry.archive.steps,
+  verify: stageRegistry.verify.steps,
+  plan: buildPlanSteps(null),
+  execute: buildExecuteSteps(null),
+}
+
+function names(stage) {
+  return stageSteps[stage].map(step => step.name)
+}
+
+function assertContains(stage, expectedNames) {
+  const actual = names(stage)
+  for (const name of expectedNames) {
+    assert.ok(actual.includes(name), `${stage} should include step "${name}". Actual: ${actual.join(', ')}`)
+  }
+}
+
+assert.equal(stageSteps.brainstorm.length, 11, 'brainstorm should expose design self-review and final confirmation separately')
+assertContains('brainstorm', ['写设计文档并自审', '用户确认并生成规范文件'])
+
+assert.equal(stageSteps.propose.length, 7, 'propose should expose generation and self-check separately')
+assertContains('propose', ['生成规范文件', '自检门控', '展示并更新进度'])
+
+assert.equal(stageSteps.scan.length, 10, 'scan base definition should stay at 10 steps before per-project expansion')
+assertContains('scan', ['构建扫描项目列表', '生成本地配置', '生成模块映射'])
+
+assert.equal(stageSteps.quick.length, 3, 'quick should remain a short auxiliary workflow')
+assertContains('quick', ['理解任务', '实现并验证', '暂存和更新记录'])
+
+assert.equal(stageSteps.archive.length, 5, 'archive should keep its five-step lifecycle')
+assertContains('archive', ['extract-module-impact', 'sync-module-docs', '确认归档'])
+
+console.log('✅ stage definition regression checks passed')