sillyspec 3.17.7 → 3.17.8

package/package.json

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

package/src/run.js

@@ -10,6 +10,24 @@ import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
 
+/**
+ * 在容器/Docker 环境下，git 可能因目录所有权不匹配报 dubious ownership。
+ * 使用 -c safe.directory= 临时参数，不污染全局 git config。
+ * @param {string} cwd - 仓库根目录
+ * @param {string[]} args - git 子命令及参数，如 ['rev-parse', 'HEAD']
+ * @returns {{ value: string, error: string|null }}
+ */
+function safeGit(cwd, args) {
+  const { execSync } = require('child_process')
+  const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
+  try {
+    const value = execSync(['git', ...fullArgs].join(' '), { encoding: 'utf8', timeout: 5000 }).trim()
+    return { value, error: null }
+  } catch (e) {
+    return { value: null, error: e.message.split('\n')[0] }
+  }
+}
+
 // ── Wait State Constants ──
 // 正则匹配：只识别独立一行的标记，避免误伤文档正文引用
 const WAIT_MARKER_RE = /^\s*\[(WAIT_FOR_USER|NEEDS_CONFIRM|NEEDS_DECISION)\]\s*$/m
@@ -129,6 +147,21 @@ async function auditQuickCompletion(cwd, guard, options = {}) {
       result.status = 'warning'
     }
 
+    // quicklog 存在性检查
+    try {
+      const quicklogDir = join(cwd, '.sillyspec', 'quicklog')
+      if (existsSync(quicklogDir)) {
+        const qlFiles = readdirSync(quicklogDir).filter(f => f.endsWith('.md'))
+        if (qlFiles.length === 0) {
+          result.reasons.push('quicklog 目录为空（无任务记录）')
+          if (result.status === 'safe') result.status = 'warning'
+        }
+      } else {
+        result.reasons.push('quicklog 目录不存在（agent 未创建任务记录）')
+        if (result.status === 'safe') result.status = 'warning'
+      }
+    } catch {}
+
     // --confirm 模式：展示 diff 并等待确认
     if (isConfirm && (result.status === 'warning' || result.status === 'blocked')) {
       console.log(`\n📋 quick 变更概览：`)
@@ -351,7 +384,7 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
   if (promptText.includes('<git-user>')) {
     const { execSync } = await import('child_process')
     try {
-      const gitUser = execSync('git config user.name', { cwd, encoding: 'utf8', timeout: 5000 }).trim()
+      const gitUser = safeGit(cwd, ['config', 'user.name']).value || 'unknown'
       promptText = promptText.replace(/<git-user>/g, gitUser)
     } catch {
       promptText = promptText.replace(/<git-user>/g, 'unknown')
@@ -377,9 +410,14 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     const docsRoot = join(specSillyspec, 'docs', projectName)
     const projectsRoot = join(specSillyspec, 'projects')
     const changesRoot = join(specSillyspec, 'changes')
+    const workflowsRoot = join(specSillyspec, 'workflows')
+    const knowledgeRoot = join(specSillyspec, 'knowledge')
 
     promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
     promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
 
     const platformDirectives = []
     platformDirectives.push(
@@ -389,6 +427,8 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
       `- 文档根目录: \`${docsRoot}/\`\n` +
       `- 项目注册表: \`${projectsRoot}/\`\n` +
       `- 变更目录: \`${changesRoot}/\`\n` +
+      `- 工作流目录: \`${workflowsRoot}/\`\n` +
+      `- 术语目录: \`${knowledgeRoot}/\`\n` +
       `\n` +
       `### ⛔ 写入规则\n` +
       `1. **所有文档、配置、产物只能写入上述路径**。严禁写入源码目录或相对路径 \`.sillyspec/\`。\n` +
@@ -437,8 +477,25 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
       const specSillyspec = join(cwd, '.sillyspec')
       const docsRoot = join(specSillyspec, 'docs', projectName)
       const projectsRoot = join(specSillyspec, 'projects')
+      const workflowsRoot = join(specSillyspec, 'workflows')
+      const knowledgeRoot = join(specSillyspec, 'knowledge')
       promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
       promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+      promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
+      promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
+      promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
+    }
+  }
+
+  // 平台模式 prompt 自检：确保没有裸相对输出路径
+  // 只匹配正向写入指令中的裸路径，避免误杀「禁止写入 .sillyspec/」等安全说明
+  if ((platformOpts?.specRoot || platformOpts?.runtimeRoot) && stageName === 'scan') {
+    const writeCtx = /(?<!不要|禁止|严禁)(?:save[\s.]+to|write|create|mkdir|git add|写入|保存到|写入到)[^a-zA-Z]*\.sillyspec\/[a-z]/i
+    if (writeCtx.test(promptText)) {
+      console.error(`❌ [sillyspec] BUG: 平台模式 scan prompt 包含写入指令指向裸相对路径 .sillyspec/`)
+      console.error(`   这会导致 agent 写入源码目录而非 spec-root，属于源码污染 bug。`)
+      console.error(`   请将路径改为对应的 {DOCS_ROOT}/{PROJECTS_ROOT}/{WORKFLOWS_ROOT}/{KNOWLEDGE_ROOT}/{SPEC_ROOT} 占位符。`)
+      process.exit(1)
     }
   }
 
@@ -651,7 +708,7 @@ async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
       const manifestDir = platformOpts.specRoot
       let sourceCommit = null
       try {
-        sourceCommit = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim()
+        const { value: sourceCommit, error: scErr } = safeGit(cwd, ['rev-parse', 'HEAD'])
       } catch {}
       mkdirSync(manifestDir, { recursive: true })
       const manifest = {
@@ -665,6 +722,7 @@ async function executeScanPostcheck(cwd, platformOpts, scanProfile) {
         workspace_id: platformOpts.workspaceId || null,
         scan_run_id: platformOpts.scanRunId || null,
         source_commit: sourceCommit,
+        source_commit_error: sourceCommit === null ? (scErr || 'unknown') : undefined,
         generated_at: new Date().toISOString(),
         schema_version: 2,
       }
@@ -1074,7 +1132,7 @@ async function runStage(pm, progress, stageName, cwd, changeName, skipApproval =
       const allowNew = quickOpts?.isAllowNew || false
       const forceBaseline = quickOpts?.isForceBaseline || false
       progress.quickGuard = {
-        baselineCommit: execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim(),
+        baselineCommit: safeGit(cwd, ['rev-parse', 'HEAD']).value,
         baselineFiles,
         allowedFiles,
         allowNew,
@@ -1668,12 +1726,13 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         mkdirSync(manifestDir, { recursive: true })
         let sourceCommit = null
         try {
-          sourceCommit = execSync('git rev-parse HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim()
+          const { value: sourceCommit, error: scErr } = safeGit(cwd, ['rev-parse', 'HEAD'])
         } catch {}
         const manifest = {
           workspace_id: platformOpts.workspaceId || null,
           scan_run_id: platformOpts.scanRunId || null,
           source_commit: sourceCommit,
+          source_commit_error: sourceCommit === null ? (scErr || 'unknown') : undefined,
           generated_at: new Date().toISOString(),
           schema_version: 1,
         }

package/src/scan-postcheck.js

@@ -52,19 +52,33 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}
 
   const projectName = basename(cwd)
 
-  // 1. source_root 污染检查
-  const localDocsDir = join(cwd, '.sillyspec', 'docs')
-  if (existsSync(localDocsDir)) {
-    try {
-      const leaked = readdirSync(localDocsDir, { recursive: true }).filter(e => String(e).endsWith('.md'))
-      if (leaked.length > 0) {
-        checks.push({
-          name: 'source_root_docs_leak',
-          severity: 'failed',
-          detail: `source_root 下存在 ${leaked.length} 个文档文件（${localDocsDir}/），agent 可能写入到了错误路径`
-        })
-      }
-    } catch {}
+  // 1. source_root 污染检查（docs/projects/workflows/knowledge/manifest/local）
+  const pollutePaths = ['docs', 'projects', 'workflows', 'knowledge']
+  const polluteFiles = ['manifest.json', 'local.yaml']
+  for (const sub of pollutePaths) {
+    const localSub = join(cwd, '.sillyspec', sub)
+    if (existsSync(localSub)) {
+      try {
+        const leaked = readdirSync(localSub, { recursive: true }).filter(e => String(e).endsWith('.md') || String(e).endsWith('.yaml') || String(e).endsWith('.json'))
+        if (leaked.length > 0) {
+          checks.push({
+            name: 'source_root_leak',
+            severity: 'failed',
+            detail: `source_root/.sillyspec/${sub}/ 下存在 ${leaked.length} 个文件（${localSub}/），agent 写入到了错误路径`
+          })
+        }
+      } catch {}
+    }
+  }
+  for (const file of polluteFiles) {
+    const filePath = join(cwd, '.sillyspec', file)
+    if (existsSync(filePath)) {
+      checks.push({
+        name: 'source_root_leak',
+        severity: 'failed',
+        detail: `source_root/.sillyspec/${file} 存在，agent 写入到了错误路径（${filePath}）`
+      })
+    }
   }
 
   // 2. spec_root 检查 7 份必需文档

package/src/stages/quick.js

@@ -22,8 +22,8 @@ export const definition = {
 9. 根据任务描述初步判断可能涉及的模块
 10. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
 
-### 创建任务记录（必须执行）
-理解完任务后，立即创建记录文件：
+### 创建任务记录（⛔ 此步骤不能跳过，没有 quicklog 记录 = 未完成）
+理解完任务后，**必须**立即创建记录文件，再输出任何其他内容：
 1. 使用预注入的 git 用户名：\`<git-user>\`
 2. 无 \`--change\`：创建 .sillyspec/quicklog/QUICKLOG-\`<git-user>\`.md\`（已存在则追加），写入：
    \`\`\`
@@ -41,7 +41,9 @@ export const definition = {
 这样 Gate 检测到 .sillyspec/\` 下有变更，就不会拦截后续的代码修改。
 
 ### 输出
-任务理解 + 上下文摘要 + quicklog 已创建`,
+quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上下文摘要
+
+⚠️ **先创建 quicklog，再输出任务理解。** 如果 quicklog 未创建，CLI post-check 会报 warning。`,
       outputHint: '任务理解',
       optional: false
     },

package/src/stages/scan.js

@@ -103,13 +103,13 @@ export const definition = {
     {
       name: '深度扫描 — 7 份文档（子代理并行）',
       perProject: true,
-      prompt: `按照 \`.sillyspec/workflows/scan-docs.yaml\` 中定义的角色和检查规则，使用子代理并行生成当前项目的 7 份扫描文档。
+      prompt: `按照 \`{WORKFLOWS_ROOT}/scan-docs.yaml\` 中定义的角色和检查规则，使用子代理并行生成当前项目的 7 份扫描文档。
 
 **你必须使用子代理执行，不要自己写文档。**
 **对扫描列表中的每个项目分别执行以下流程。**
 
 ### 操作
-1. 读取 \`.sillyspec/workflows/scan-docs.yaml\`，了解角色定义、输出要求和检查规则
+1. 读取 \`{WORKFLOWS_ROOT}/scan-docs.yaml\`，了解角色定义、输出要求和检查规则
 2. 对每个项目（扫描列表中标记为需生成/覆盖的项目）：
    a. 将 \`<project>\` 替换为实际项目名，得到该项目的目标文件路径
    b. 为每个角色启动独立子代理（可并行），每个子代理负责 1-2 份文档
@@ -141,16 +141,16 @@ export const definition = {
     },
     {
       name: '生成本地配置',
-      prompt: `自动生成 .sillyspec/local.yaml 本地配置文件。
+      prompt: `自动生成 local.yaml 本地配置文件。
 
 ### 操作
-1. 检查 .sillyspec/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
+1. 检查 {SPEC_ROOT}/local.yaml 是否已存在，已存在则跳过（提示"local.yaml 已存在，跳过生成"）
 2. 根据项目类型生成默认配置：
    - **Node.js**（有 package.json）：build: "npm run build", test: "npm test", lint: "npm run lint", type: nodejs
    - **Maven**（有 pom.xml）：build: "mvn compile", test: "mvn test", lint: "mvn checkstyle:check", type: maven
    - **Gradle**（有 build.gradle）：build: "./gradlew build", test: "./gradlew test", type: gradle
    - **通用项目**：只写注释模板, type: generic
-3. 确保目录存在：mkdir -p .sillyspec
+3. 确保目录存在：mkdir -p {SPEC_ROOT}
 4. 原子写入（先写 tmp 文件再 rename）
 
 ### 文件格式
@@ -454,7 +454,7 @@ step1 → step2 → step3
 3. 自检门控：ARCHITECTURE（技术栈+Schema摘要）、CONVENTIONS（隐形规则+代码风格）、STRUCTURE（目录结构）、INTEGRATIONS（外部依赖）、TESTING（测试现状）、CONCERNS（技术债务）、PROJECT（项目概览）
 4. 检查 flows/ 和 glossary.md 是否已生成（如有）
 5. 清理：\`rm -f {DOCS_ROOT}/scan/_env-detect.md\`
-6. \`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）
+6. 如果非平台模式：\`git add .sillyspec/\` — 暂存扫描结果（不要 commit，由用户通过统一提交工具处理）。如果平台模式：跳过 git add（specRoot 不在 sourceRoot 的 git repo 内）。
 
 ### ⛔ 路径合规检查（平台模式下必须执行）
 7. 确认所有文档都写入 \`{DOCS_ROOT}/\`（spec-root 下），**而非源码目录下的 .sillyspec/**

package/test/platform-scan-p0.test.mjs

@@ -0,0 +1,172 @@
+/**
+ * P0 补丁验证 — 4 类测试
+ *
+ * 1. 平台 scan prompt 不含正向写入 .sillyspec/ 指令
+ * 2. 安全说明文字不被 prompt 自检误杀
+ * 3. 平台模式不执行 git add {SPEC_ROOT}
+ * 4. source_root 污染检查覆盖所有子目录/文件
+ * 5. run.js 占位符替换补齐（平台+本地）
+ *
+ * 跑法: node test/platform-scan-p0.test.mjs
+ */
+
+import { join, basename } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync, readdirSync } from 'fs'
+import { execSync } from 'child_process'
+import { readFile } from 'fs/promises'
+import { fileURLToPath } from 'url'
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
+const passed = []
+const failed = []
+
+function assert(label, condition, detail) {
+  if (condition) {
+    passed.push(label)
+  } else {
+    failed.push({ label, detail })
+  }
+}
+
+// ── 测试 1：scan.js 模板不含裸 .sillyspec 输出路径 ──
+{
+  const { definition } = await import('../src/stages/scan.js')
+  const prompts = definition.steps.map(s => s.prompt).join('\n')
+
+  // 所有 .sillyspec 出现都应该是「禁止说明」，不是写入指令
+  const writePatterns = [
+    /write.*\.sillyspec\/docs/i,
+    /save.*\.sillyspec\/docs/i,
+    /create.*\.sillyspec\/docs/i,
+    /mkdir.*\.sillyspec\/docs/i,
+  ]
+  for (const p of writePatterns) {
+    assert(`scan 模板无写入 .sillyspec/docs: ${p}`, !p.test(prompts),
+      p.test(prompts) ? `命中: ${prompts.match(p)[0]}` : '')
+  }
+
+  // 应该使用占位符
+  assert('scan 模板使用 {WORKFLOWS_ROOT}', prompts.includes('{WORKFLOWS_ROOT}'))
+  assert('scan 模板使用 {SPEC_ROOT}', prompts.includes('{SPEC_ROOT}'))
+  assert('scan 模板使用 {DOCS_ROOT}', prompts.includes('{DOCS_ROOT}'))
+
+  // 平台模式下 git add 应该是条件判断
+  assert('scan 模板平台模式跳过 git add', prompts.includes('如果平台模式：跳过 git add'))
+  assert('scan 模板非平台模式 git add .sillyspec/', prompts.includes('git add .sillyspec/'))
+}
+
+// ── 测试 2：prompt 自检不误杀安全说明 ──
+{
+  // 导入 run.js 中的正则
+  const writeCtxRe = /(?<!不要|禁止|严禁)(?:save[\s.]+to|write|create|mkdir|git add|写入|保存到|写入到)[^a-zA-Z]*\.sillyspec\/[a-z]/i
+
+  // 安全说明 — 不应命中
+  const safeLines = [
+    '严禁写入源码目录或相对路径 `.sillyspec/`',
+    '⚠️ 不要写入 .sillyspec/docs',
+    'source_root 下存在 .sillyspec/docs 文件',
+    '不允许从 cwd 推导 .sillyspec 路径',
+  ]
+  for (const line of safeLines) {
+    assert(`安全说明不误杀: "${line.slice(0, 40)}"`, !writeCtxRe.test(line),
+      '误杀! 命中了安全说明文字')
+  }
+
+  // 写入指令 — 应该命中
+  const badLines = [
+    '写入 `.sillyspec/docs/ARCHITECTURE.md`',
+    'save to `.sillyspec/docs/ARCHITECTURE.md`',
+    'create `.sillyspec/docs/ARCH.md`',
+    'git add .sillyspec/docs/',
+    'write 到 .sillyspec/docs/',
+  ]
+  for (const line of badLines) {
+    assert(`写入指令应命中: "${line.slice(0, 40)}"`, writeCtxRe.test(line),
+      '漏杀! 没有捕获写入指令')
+  }
+}
+
+// ── 测试 3：safeGit 使用 -c safe.directory（不污染全局 config） ──
+{
+  const runSrc = await readFile(join(__dirname, '..', 'src', 'run.js'), 'utf8')
+
+  assert('safeGit 不含 --global', !runSrc.includes('git config --global'),
+    '发现 --global，会污染容器 git config')
+
+  assert('safeGit 使用 -c safe.directory', runSrc.includes("safe.directory=${cwd}"),
+    '未发现 -c safe.directory per-command 参数')
+
+  assert('safeGit 使用 -C cwd', runSrc.includes("-C', cwd"),
+    '未发现 -C cwd 参数')
+
+  assert('safeGit 返回 { value, error }', runSrc.includes("return { value, error: "),
+    'safeGit 返回值不是 { value, error } 结构')
+
+  assert('manifest 包含 source_commit_error 字段',
+    runSrc.includes("source_commit_error:"), 'manifest 缺少 source_commit_error')
+}
+
+// ── 测试 4：postcheck 污染检查覆盖所有子目录 ──
+{
+  const postcheckSrc = await readFile(join(__dirname, '..', 'src', 'scan-postcheck.js'), 'utf8')
+
+  const requiredSubs = ['docs', 'projects', 'workflows', 'knowledge']
+  for (const sub of requiredSubs) {
+    assert(`postcheck 检查 ${sub} 污染`,
+      postcheckSrc.includes(`'${sub}'`) && postcheckSrc.includes("'.sillyspec', sub)"),
+      `postcheck 未检查 .sillyspec/${sub}/ 污染`)
+  }
+
+  assert('postcheck 检查 manifest.json', postcheckSrc.includes('manifest.json'))
+  assert('postcheck 检查 local.yaml', postcheckSrc.includes('local.yaml'))
+  assert('污染 severity 为 failed', postcheckSrc.includes("severity: 'failed'"))
+}
+
+// ── 测试 5：run.js 占位符替换补齐 ──
+{
+  const runSrc = await readFile(join(__dirname, '..', 'src', 'run.js'), 'utf8')
+
+  // 平台模式块
+  const platformMarker = 'promptText.replace(/\\{WORKFLOWS_ROOT\\}'
+  assert('平台模式替换 {WORKFLOWS_ROOT}', runSrc.includes('{WORKFLOWS_ROOT}') && runSrc.includes('workflowsRoot'))
+  assert('平台模式替换 {KNOWLEDGE_ROOT}', runSrc.includes('{KNOWLEDGE_ROOT}') && runSrc.includes('knowledgeRoot'))
+  assert('平台模式替换 {SPEC_ROOT}', runSrc.includes('{SPEC_ROOT}') && runSrc.includes("specSillyspec"))
+
+  // 非平台模式块
+  assert('非平台模式替换 {WORKFLOWS_ROOT}', runSrc.includes('workflowsRoot'))
+  assert('非平台模式替换 {KNOWLEDGE_ROOT}', runSrc.includes('knowledgeRoot'))
+  assert('非平台模式替换 {SPEC_ROOT}', runSrc.includes('{SPEC_ROOT}'))
+}
+
+// ── 测试 6：quick step 1 prompt 强制要求 quicklog ──
+{
+  const { definition } = await import('../src/stages/quick.js')
+  const step1Prompt = definition.steps[0].prompt
+
+  assert('quick step 1 包含 ⛔ 标记', step1Prompt.includes('⛔'))
+  assert('quick step 1 包含「不能跳过」', step1Prompt.includes('不能跳过'))
+  assert('quick step 1 包含 quicklog 未创建 warning', step1Prompt.includes('quicklog 未创建'))
+  assert('quick step 1 输出要求 quicklog 第一行', step1Prompt.includes('第一行确认'))
+
+  // run.js 审计包含 quicklog 检查
+  const runSrc = await readFile(join(__dirname, '..', 'src', 'run.js'), 'utf8')
+  assert('quick 审计检查 quicklog 目录存在', runSrc.includes('quicklog 目录不存在'))
+  assert('quick 审计检查 quicklog 为空', runSrc.includes('quicklog 目录为空'))
+}
+
+// ── 结果 ──
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed.length}`)
+console.log(`❌ 失败: ${failed.length}`)
+console.log(`${'='.repeat(50)}`)
+
+if (failed.length > 0) {
+  console.log('\n失败详情:')
+  for (const f of failed) {
+    console.log(`  ❌ ${f.label}`)
+    if (f.detail) console.log(`     ${f.detail}`)
+  }
+  process.exit(1)
+} else {
+  console.log('\n🎉 全部 P0 测试通过!')
+}