sillyspec 3.17.7 → 3.17.9

package/package.json

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

package/src/modules.js

@@ -47,7 +47,18 @@ function parseModuleCardFrontmatter(content) {
 }
 
 /**
- * rebuild: 从模块卡片 + 源码重建 _module-map.yaml
+ * 从模块卡片 + 源码重建 _module-map.yaml
+ *
+ * schema_version 2 扩展字段：
+ *   - role: 模块职责描述
+ *   - core_files: 核心源文件列表
+ *   - test_files: 测试文件列表
+ *   - entrypoints: 入口点
+ *   - depends_on: 依赖的其他模块
+ *   - used_by: 被哪些模块使用
+ *   - risk_level: 风险等级（low/medium/high）
+ *   - verify_commands: 验证命令（build/test/lint）
+ *   - related_docs: 关联文档路径
  */
 export async function rebuildModuleMap(cwd) {
   const mapPath = findModuleMapPath(cwd);
@@ -107,10 +118,12 @@ export async function rebuildModuleMap(cwd) {
     headCommit = execSync('git rev-parse --short HEAD', { cwd, encoding: 'utf8', timeout: 5000 }).trim();
   } catch { /* ignore */ }
 
-  let yaml = `schema_version: 1\n`;
+  let yaml = `schema_version: 2\n`;
   yaml += `generated_at: ${now}\n`;
   yaml += `generator: sillyspec-modules-rebuild\n`;
   if (headCommit) yaml += `source_commit: ${headCommit}\n`;
+  yaml += `\n# Module Context Index — 机器可读的模块上下文索引\n`;
+  yaml += `# scan 阶段自动生成，brainstorm/plan/execute 阶段按任务命中模块精准注入上下文\n`;
   yaml += `\nmodules:\n`;
 
   // 合并：已有映射 + 新卡片
@@ -121,13 +134,31 @@ export async function rebuildModuleMap(cwd) {
 
   for (const moduleId of allModuleIds) {
     const card = cards.find(c => c.moduleId === moduleId);
+    const cardContent = card ? readFileSync(join(modulesDir, card.filename), 'utf8') : '';
+
+    // 从模块卡片提取 context index 字段
+    const role = extractSection(cardContent, '定位') || '';
+    const contract = extractSection(cardContent, '契约摘要') || '';
+    const logic = extractSection(cardContent, '关键逻辑') || '';
+    const notes = extractSection(cardContent, '注意事项') || '';
+
     yaml += `  ${moduleId}:\n`;
     yaml += `    status: active\n`;
     if (card) yaml += `    doc: modules/${card.filename}\n`;
     else yaml += `    doc: modules/${moduleId}.md\n`;
-    // 保留已有 _module-map.yaml 中的 paths 等字段（如果有的话）
     yaml += `    needs_review: false\n`;
     yaml += `    review_reasons: []\n`;
+    // context index 字段（v2）
+    if (role) yaml += `    role: "${escapeYamlString(role)}"\n`;
+    // core_files / test_files / entrypoints 从已有 _module-map 保留，或从卡片文件名推导
+    const existingPaths = existingModules[moduleId]?.paths || [];
+    if (existingPaths.length > 0) {
+      yaml += `    core_files:\n`;
+      for (const p of existingPaths) yaml += `      - ${p}\n`;
+    }
+    if (card) yaml += `    verify_commands: []\n`;
+    yaml += `    risk_level: low\n`;
+    if (contract || logic) yaml += `    related_docs: []\n`;
     yaml += `\n`;
   }
 
@@ -138,6 +169,7 @@ export async function rebuildModuleMap(cwd) {
     console.log(`   - ${id}`);
   }
   console.log(`\n⚠️  注意：rebuild 只重建骨架。tags/entrypoints/main_symbols/depends_on/used_by 需要重新运行 scan 或手动补充。`);
+  console.log(`ℹ️  schema 已升级到 v2，支持 role/core_files/test_files/entrypoints/depends_on/risk_level/verify_commands 等字段。`);
 }
 
 /**
@@ -163,13 +195,17 @@ export async function showModuleStatus(cwd) {
     const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):$/);
     if (moduleMatch) {
       if (currentModule) modules.push(currentModule);
-      currentModule = { id: moduleMatch[1], hasTags: false, hasEntryPoints: false, hasDepends: false, needsReview: false };
+      currentModule = { id: moduleMatch[1], hasTags: false, hasEntryPoints: false, hasDepends: false, needsReview: false, hasRole: false, hasCoreFiles: false, hasRisk: false, hasVerify: false };
     }
     if (currentModule) {
       if (line.includes('tags:')) currentModule.hasTags = true;
       if (line.includes('entrypoints:')) currentModule.hasEntryPoints = true;
       if (line.includes('depends_on:')) currentModule.hasDepends = true;
       if (line.includes('needs_review: true')) { currentModule.needsReview = true; needsReview = true; }
+      if (line.includes('role:')) currentModule.hasRole = true;
+      if (line.includes('core_files:')) currentModule.hasCoreFiles = true;
+      if (line.includes('risk_level:')) currentModule.hasRisk = true;
+      if (line.includes('verify_commands:')) currentModule.hasVerify = true;
     }
   }
   if (currentModule) modules.push(currentModule);
@@ -178,14 +214,18 @@ export async function showModuleStatus(cwd) {
   console.log(`模块数量：${modules.length}\n`);
 
   const maxId = Math.max(5, ...modules.map(m => m.id.length));
-  console.log(`  ${'模块'.padEnd(maxId)}  tags  entry  deps  review`);
-  console.log(`  ${'─'.repeat(maxId)}  ────  ─────  ────  ──────`);
+  console.log(`  ${'模块'.padEnd(maxId)}  tags  entry  deps  role  core  risk  review`);
+  console.log(`  ${''.padEnd(maxId, '─')}  ────  ─────  ────  ────  ────  ────  ──────`);
   for (const m of modules) {
     const tags = m.hasTags ? '✅' : '⬜';
     const entry = m.hasEntryPoints ? '✅' : '⬜';
     const deps = m.hasDepends ? '✅' : '⬜';
+    const role = m.hasRole ? '✅' : '⬜';
+    const core = m.hasCoreFiles ? '✅' : '⬜';
+    const risk = m.hasRisk ? '✅' : '⬜';
+    const verify = m.hasVerify ? '✅' : '⬜';
     const review = m.needsReview ? '⚠️' : '✅';
-    console.log(`  ${m.id.padEnd(maxId)}  ${tags}     ${entry}     ${deps}     ${review}`);
+    console.log(`  ${m.id.padEnd(maxId)}  ${tags}     ${entry}     ${deps}     ${role}     ${core}     ${risk}     ${verify}     ${review}`);
   }
 
   if (needsReview) {
@@ -194,7 +234,22 @@ export async function showModuleStatus(cwd) {
 }
 
 /**
- * 从 _module-map.yaml 聚合生成 dependencies.md
+ * 从模块卡片提取指定 section 的内容
+ */
+function extractSection(content, sectionName) {
+  const match = content.match(new RegExp(`## ${escapeRegExp(sectionName)}\\n([\\s\\S]*?)(?=\\n##|$)`));
+  return match ? match[1].trim().split('\n')[0] : '';  // 只取第一行作为摘要
+}
+
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function escapeYamlString(s) {
+  return s.replace(/"/g, '\\"').replace(/\n/g, ' ').slice(0, 200);  // 截断避免过长
+}
+
+/**
  */
 export async function generateDependenciesMd(cwd) {
   const mapPath = findModuleMapPath(cwd);

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
@@ -46,6 +64,160 @@ import { buildExecuteSteps } from './stages/execute.js'
 import { buildPlanSteps } from './stages/plan.js'
 import { formatExecuteSummary } from './worktree-apply.js'
 
+/**
+ * 从 _module-map.yaml 读取模块上下文索引
+ * 用于 brainstorm/plan/execute 阶段按任务命中模块精准注入上下文
+ *
+ * @param {string} specBase - 规范目录（.sillyspec 或 specRoot）
+ * @param {string} projectName - 项目名
+ * @returns {object|null} 解析后的模块索引，null 表示无索引
+ */
+function loadModuleContextIndex(specBase, projectName) {
+  try {
+    const { existsSync, readFileSync } = require('fs')
+    const { join } = require('path')
+    const mapPath = join(specBase, 'docs', projectName, 'modules', '_module-map.yaml')
+    if (!existsSync(mapPath)) return null
+    const content = readFileSync(mapPath, 'utf8')
+    return parseModuleMapSimple(content)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 根据 AI 输出的任务描述，匹配相关模块并生成上下文注入文本
+ * 匹配策略：模块 id / role / doc 路径中的关键词
+ *
+ * @param {string} taskDescription - 任务描述（来自 plan.md / step prompt / outputText）
+ * @param {object} moduleIndex - loadModuleContextIndex 返回值
+ * @param {string} specBase - 规范目录
+ * @param {string} projectName - 项目名
+ * @returns {string} 上下文注入文本，空字符串表示无匹配模块
+ */
+const MAX_MODULE_CONTEXT_CHARS = 4096  // 上下文注入硬限制（字节），防止 prompt 膨胀
+const MAX_MODULES_PER_INJECTION = 3   // 最多注入的模块数
+const MAX_FILES_PER_MODULE = 8        // 每个模块最多展示的文件数
+
+function buildModuleContextInjection(taskDescription, moduleIndex, specBase, projectName) {
+  if (!moduleIndex || !taskDescription) return ''
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+
+  const taskLower = taskDescription.toLowerCase()
+  const matched = []
+
+  for (const [moduleId, data] of Object.entries(moduleIndex)) {
+    let score = 0
+    let matchReasons = []
+    // 模块 id 匹配
+    if (taskLower.includes(moduleId.toLowerCase())) { score += 3; matchReasons.push(`id:${moduleId}`) }
+    // role 描述匹配
+    if (data.role && taskLower.includes(data.role.toLowerCase())) { score += 2; matchReasons.push('role') }
+    // core_files 路径匹配
+    const coreFiles = data.paths || data.core_files || []
+    for (const p of coreFiles) {
+      if (taskLower.includes(p.toLowerCase())) { score += 1; matchReasons.push(`file:${p}`); break }  // 文件匹配只计一次
+    }
+    if (score > 0) matched.push({ moduleId, data, score, matchReasons })
+  }
+
+  if (matched.length === 0) return ''
+
+  matched.sort((a, b) => b.score - a.score)
+  const top = matched.slice(0, MAX_MODULES_PER_INJECTION)
+
+  let injection = '\n### 📦 模块上下文（按相关性排序，来自 Module Context Index）\n\n'
+  injection += `> 以下模块上下文由 scan 阶段生成的 _module-map.yaml 自动匹配。\n`
+  injection += `> Matched modules: ${top.map(m => m.moduleId).join(', ')}\n`
+  injection += `> Reasons: ${top.map(m => m.matchReasons.join(', ')).join('; ')}\n\n`
+
+  for (const { moduleId, data } of top) {
+    injection += `#### ${moduleId}\n`
+    if (data.role) injection += `- **职责**: ${String(data.role).slice(0, 100)}\n`
+    const riskLevel = data.risk_level || 'medium'
+    injection += `- **风险等级**: ${riskLevel}\n`
+    const coreFiles = (data.paths || data.core_files || []).slice(0, MAX_FILES_PER_MODULE)
+    if (coreFiles.length > 0) injection += `- **核心文件**: ${coreFiles.join(', ')}\n`
+    if (data.doc) {
+      const docPath = join(specBase, 'docs', projectName, data.doc)
+      const exists = existsSync(docPath)
+      injection += `- **模块文档**: ${data.doc}${exists ? ' ✅' : ' ⚠️ 不存在'}\n`
+    }
+    const deps = data.depends_on || []
+    if (deps.length > 0) injection += `- **依赖**: ${deps.slice(0, 5).join(', ')}\n`
+    const usedBy = data.used_by || []
+    if (usedBy.length > 0) injection += `- **被引用**: ${usedBy.slice(0, 5).join(', ')}\n`
+    injection += '\n'
+
+    // 长度硬限制：超过阈值截断
+    if (injection.length > MAX_MODULE_CONTEXT_CHARS) {
+      injection += `<!-- Module context truncated: exceeded ${MAX_MODULE_CONTEXT_CHARS} chars -->\n`
+      break
+    }
+  }
+
+  return injection
+}
+
+// 复用 modules.js 的简单 YAML 解析（避免循环依赖）
+function parseModuleMapSimple(content) {
+  const modules = {}
+  let currentModule = null
+  let currentKey = null
+  let currentArray = null
+
+  for (const line of content.split('\n')) {
+    const moduleMatch = line.match(/^  ([a-zA-Z0-9_-]+):$/)
+    if (moduleMatch) {
+      if (currentArray && currentModule && currentKey) {
+        modules[currentModule][currentKey] = currentArray
+      }
+      currentModule = moduleMatch[1]
+      modules[currentModule] = {}
+      currentKey = null
+      currentArray = null
+      continue
+    }
+    if (!currentModule) continue
+
+    const arrayFieldMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands):$/)
+    if (arrayFieldMatch) {
+      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
+      currentKey = arrayFieldMatch[1]
+      currentArray = []
+      continue
+    }
+
+    const inlineArrayMatch = line.match(/^    (depends_on|used_by|paths|tags|aliases|entrypoints|main_symbols|review_reasons|core_files|test_files|related_docs|verify_commands): \[(.*)\]$/)
+    if (inlineArrayMatch) {
+      if (currentArray && currentKey) modules[currentModule][currentKey] = currentArray
+      const vals = inlineArrayMatch[2].split(',').map(v => v.trim()).filter(Boolean)
+      modules[currentModule][inlineArrayMatch[1]] = vals
+      currentKey = null
+      currentArray = null
+      continue
+    }
+
+    const scalarMatch = line.match(/^    (status|doc|needs_review|role|risk_level): (.+)$/)
+    if (scalarMatch) {
+      if (currentArray && currentKey) { modules[currentModule][currentKey] = currentArray; currentArray = null; currentKey = null }
+      modules[currentModule][scalarMatch[1]] = scalarMatch[2]
+      continue
+    }
+
+    const itemMatch = line.match(/^      - (.+)$/)
+    if (itemMatch && currentArray !== null) {
+      currentArray.push(itemMatch[1].trim())
+      continue
+    }
+  }
+  if (currentArray && currentModule && currentKey) {
+    modules[currentModule][currentKey] = currentArray
+  }
+  return modules
+}
+
 /**
  * 同步触发辅助函数：_write 后 best-effort 同步到平台
  */
@@ -129,6 +301,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 +538,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 +564,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 +581,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 +631,38 @@ 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)
+    }
+  }
+
+  // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
+  if (['brainstorm', 'plan', 'execute'].includes(stageName) && projectName) {
+    const moduleIndex = loadModuleContextIndex(specBase || join(cwd, '.sillyspec'), projectName)
+    if (moduleIndex && Object.keys(moduleIndex).length > 0) {
+      // 尝试从 step prompt / changeName 匹配模块
+      const taskDesc = step.prompt || changeName || ''
+      const injection = buildModuleContextInjection(taskDesc, moduleIndex, specBase || join(cwd, '.sillyspec'), projectName)
+      if (injection) {
+        promptText = injection + '\n' + promptText
+      }
+    }
+  }
+
+  // 平台模式 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 +875,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 +889,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 +1299,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 +1893,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,
         }
@@ -1690,7 +1916,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         try { unlinkSync(platformOptsFile) } catch {}
 
         // CLI 层 post-check（替代旧的简单检查）
-        const { runScanPostCheck, printScanPostCheckResult } = await import('./scan-postcheck.js')
+        const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('./scan-postcheck.js')
         const postResult = runScanPostCheck({
           cwd,
           specDir: platformOpts.specRoot,
@@ -1702,6 +1928,22 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         })
         printScanPostCheckResult(postResult)
 
+        // 生成结构化 JSON 并写入 runtime（供 SillyHub 消费）
+        const structured = formatStructuredResult(postResult, {
+          workspace_id: platformOpts.workspaceId,
+          scan_run_id: platformOpts.scanRunId,
+          source_root: cwd,
+          spec_root: platformOpts.specRoot,
+          runtime_root: platformOpts.runtimeRoot,
+        })
+        const postcheckJsonPath = writeStructuredResult(structured, platformOpts.specRoot, {
+          runtimeRoot: platformOpts.runtimeRoot,
+          scanRunId: platformOpts.scanRunId,
+        })
+        if (postcheckJsonPath) {
+          console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+        }
+
         // 将 post-check 结果写入 manifest
         manifest.scan_post_check = {
           status: postResult.status,
@@ -1729,11 +1971,17 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
       }
     }
 
-    // 非 platform 模式 scan 也做轻量 post-check
+    // 非 platform 模式 scan 也做轻量 post-check + 结构化输出
     if (stageName === 'scan' && !platformOpts.specRoot && !platformOpts.runtimeRoot) {
-      const { runScanPostCheck, printScanPostCheckResult } = await import('./scan-postcheck.js')
+      const { runScanPostCheck, printScanPostCheckResult, formatStructuredResult, writeStructuredResult } = await import('./scan-postcheck.js')
       const postResult = runScanPostCheck({ cwd, specDir: null, outputText })
       printScanPostCheckResult(postResult)
+      // 结构化结果写入 .sillyspec/.runtime/
+      const structured = formatStructuredResult(postResult, { source_root: cwd })
+      const postcheckJsonPath = writeStructuredResult(structured, join(cwd, '.sillyspec'))
+      if (postcheckJsonPath) {
+        console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+      }
     }
 
     validateMetadata(cwd, stageName, specBase)

package/src/scan-postcheck.js

@@ -5,7 +5,7 @@
  * 平台模式下必须通过所有 check 才能 success，否则降级。
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs'
+import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from 'fs'
 import { join, basename } from 'path'
 
 const REQUIRED_SCAN_DOCS = [
@@ -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 份必需文档
@@ -184,6 +198,138 @@ export function runScanPostCheck({ cwd, specDir, outputText = '', scanMeta = {}
   return { status, checks }
 }
 
+/**
+ * 将 postcheck 结果转换为结构化 JSON（SillyHub 可消费格式）
+ *
+ * failure_category 标准化：
+ *   - warning  : 非致命问题，不阻塞流程
+ *   - error    : 文档缺失/内容不完整，需要修复
+ *   - critical : 安全问题（source_root 泄漏/路径污染）
+ *
+ * 结构化字段：
+ *   - violations      : 明确违反约束的条目（source_root 泄漏等）
+ *   - missing_outputs : 预期文件不存在
+ *   - path_pollution  : 产物写入了错误路径
+ *   - bad_references  : 引用了不存在的命令/资源
+ *   - quality_warnings: AI 输出中包含错误标记等质量信号
+ *
+ * @param {object} result - runScanPostCheck 返回值
+ * @param {object} [meta] - 附带元数据（workspace_id, scan_run_id, timestamp 等）
+ * @returns {object} 结构化 JSON
+ */
+export function formatStructuredResult(result, meta = {}) {
+  const structured = {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    overall_status: result.status,
+    // 路径溯源（供平台消费）
+    ...(meta.workspace_id ? { workspace_id: meta.workspace_id } : {}),
+    ...(meta.scan_run_id ? { scan_run_id: meta.scan_run_id } : {}),
+    ...(meta.source_root ? { source_root: meta.source_root } : {}),
+    ...(meta.spec_root ? { spec_root: meta.spec_root } : {}),
+    ...(meta.runtime_root ? { runtime_root: meta.runtime_root } : {}),
+    summary: {
+      total_checks: result.checks.length,
+      critical: 0,
+      error: 0,
+      warning: 0,
+    },
+    failure_categories: {
+      violations: [],
+      missing_outputs: [],
+      path_pollution: [],
+      bad_references: [],
+      quality_warnings: [],
+    },
+    checks: result.checks.map(c => ({
+      name: c.name,
+      severity: c.severity === 'failed' ? 'critical' : c.severity,
+      detail: c.detail,
+    })),
+  }
+
+  // 分类到 failure_categories
+  for (const check of result.checks) {
+    const severity = check.severity === 'failed' ? 'critical' : check.severity
+    const entry = { name: check.name, detail: check.detail, severity }
+
+    // 路径污染类
+    if (check.name === 'source_root_leak') {
+      structured.failure_categories.path_pollution.push(entry)
+      structured.failure_categories.violations.push(entry)
+    }
+    // 文档缺失类
+    else if (check.name === 'all_docs_missing' || check.name === 'partial_docs_missing' || check.name === 'missing_docs') {
+      structured.failure_categories.missing_outputs.push(entry)
+    }
+    // 引用无效类
+    else if (check.name === 'local_config_invalid') {
+      structured.failure_categories.bad_references.push(entry)
+    }
+    // AI 输出质量类
+    else if (['tool_use_error', 'api_error_529', 'rate_limit_exhausted', 'fallback_or_skip'].includes(check.name)) {
+      structured.failure_categories.quality_warnings.push(entry)
+    }
+    // manifest/project 列表问题
+    else if (check.name === 'manifest_write_failed' || check.name === 'project_list_parse_failed') {
+      structured.failure_categories.violations.push(entry)
+    }
+    // 文档缺少 header
+    else if (check.name === 'docs_missing_header') {
+      structured.failure_categories.quality_warnings.push(entry)
+    }
+    // 兜底：归入 violations
+    else {
+      structured.failure_categories.violations.push(entry)
+    }
+  }
+
+  // 汇总计数
+  for (const check of result.checks) {
+    if (check.severity === 'failed') structured.summary.critical++
+    else structured.summary.warning++
+  }
+
+  return structured
+}
+
+/**
+ * 将结构化结果写入 JSON 文件（平台模式供 SillyHub 消费）
+ *
+ * 本地模式：写入 specDir/.runtime/postcheck-result.json
+ * 平台模式：写入 runtimeRoot/scan-runs/{scan_run_id}/postcheck-result.json
+ *
+ * @param {object} structured - formatStructuredResult 返回值
+ * @param {string} specDir - 规范目录（本地模式使用）
+ * @param {object} [opts] - 平台模式选项
+ * @param {string} [opts.runtimeRoot] - 平台模式运行时根目录
+ * @param {string} [opts.scanRunId] - scan run ID
+ * @returns {string|null} 写入的文件路径，失败时返回 null
+ */
+export function writeStructuredResult(structured, specDir, opts = {}) {
+  if (!specDir && !opts.runtimeRoot) return null
+  try {
+    let outPath
+    if (opts.runtimeRoot && opts.scanRunId) {
+      const scanRunDir = join(opts.runtimeRoot, 'scan-runs', opts.scanRunId)
+      mkdirSync(scanRunDir, { recursive: true })
+      outPath = join(scanRunDir, 'postcheck-result.json')
+    } else if (specDir) {
+      const runtimeDir = join(specDir, '.runtime')
+      mkdirSync(runtimeDir, { recursive: true })
+      outPath = join(runtimeDir, 'postcheck-result.json')
+    } else {
+      return null
+    }
+
+    writeFileSync(outPath, JSON.stringify(structured, null, 2) + '\n')
+    return outPath
+  } catch (e) {
+    console.warn(`  ⚠️ postcheck-result.json 写入失败: ${e.message}`)
+    return null
+  }
+}
+
 /**
  * 打印 post-check 结果到 stdout
  */

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 测试通过!')
+}