sillyspec 3.20.3 → 3.20.4

package/test/run-sanitize-project-name.test.mjs

@@ -0,0 +1,51 @@
+/**
+ * task-09: sanitizeProjectName 字母校验 + 长度≥2 + 编号正则收紧
+ *
+ * 覆盖：
+ * - 纯数字 "0"/"7" → null（核心目标，scan-projects.json 脏数据来源）
+ * - "0/7" 清洗 "07" 无字母 → null
+ * - "a" 长度<2 → null
+ * - "fe" 含字母长度≥2 → 通过
+ * - "frontend" / "order-service" → 通过
+ * - "前端项目" 全中文清洗后 "" → null
+ * - "" → null
+ */
+import { sanitizeProjectName } from '../src/run.js'
+
+let passed = 0
+let failed = 0
+function assertEqual (actual, expected, msg) {
+  const ok = actual === expected
+  if (ok) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   expected: ${JSON.stringify(expected)}\n   actual:   ${JSON.stringify(actual)}`); failed++ }
+}
+
+// 通过用例
+assertEqual(sanitizeProjectName('frontend'), 'frontend', '"frontend" 含字母长度≥2 通过')
+assertEqual(sanitizeProjectName('order-service'), 'order-service', '"order-service" 含字母+横线 通过')
+assertEqual(sanitizeProjectName('fe'), 'fe', '"fe" 最小长度 2 通过')
+assertEqual(sanitizeProjectName('user_service'), 'user_service', '"user_service" 含下划线 通过')
+assertEqual(sanitizeProjectName('app.v2'), 'app.v2', '"app.v2" 含点+数字 通过')
+
+// 拒绝用例（核心目标）
+assertEqual(sanitizeProjectName('0'), null, '"0" 纯数字拒绝')
+assertEqual(sanitizeProjectName('7'), null, '"7" 纯数字拒绝')
+assertEqual(sanitizeProjectName('07'), null, '"07" 纯数字拒绝（无字母）')
+assertEqual(sanitizeProjectName('0/7'), null, '"0/7" 清洗后 "07" 无字母拒绝')
+assertEqual(sanitizeProjectName('123'), null, '"123" 纯数字拒绝')
+
+// 长度<2
+assertEqual(sanitizeProjectName('a'), null, '"a" 长度<2 拒绝（即使含字母）')
+assertEqual(sanitizeProjectName('z'), null, '"z" 长度<2 拒绝')
+
+// 中文 / 空
+assertEqual(sanitizeProjectName('前端项目'), null, '"前端项目" 全中文清洗后 "" 拒绝')
+assertEqual(sanitizeProjectName(''), null, '空字符串拒绝')
+assertEqual(sanitizeProjectName('   '), null, '纯空白拒绝')
+assertEqual(sanitizeProjectName(null), null, 'null 拒绝')
+assertEqual(sanitizeProjectName(undefined), null, 'undefined 拒绝')
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+if (failed > 0) process.exit(1)

package/test/run-scan-postcheck-fail.test.mjs

@@ -0,0 +1,64 @@
+/**
+ * task-06: scan post-check 失败补 return + completed 标记推迟 + 平台模式 exit(1)
+ *
+ * 验证点：
+ * - AC-1: run.js:2433-2438 失败分支末尾补 return { stageCompleted:false, currentIdx, nextPendingIdx: currentIdx }
+ * - AC-2: 平台模式 (platformOpts.specRoot || platformOpts.runtimeRoot) 时 process.exit(1)
+ * - AC-3: 返回结构与 plan contract (run.js:2551 附近) 完全一致
+ * - AC-4: 非平台模式不 exit（只有 if platformOpts 守卫内的 exit）
+ */
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const runPath = join(__dirname, '..', 'src', 'run.js')
+const src = readFileSync(runPath, 'utf8')
+
+let passed = 0
+let failed = 0
+function check (cond, msg) {
+  if (cond) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}`); failed++ }
+}
+
+// 定位 scan post-check failed_post_check 分支
+// 已知关键锚：stageData.status = SCAN_STATUS.FAILED_POST_CHECK
+const failedAnchor = src.indexOf("postResult.status === 'failed_post_check'")
+check(failedAnchor > 0, "源码含 'failed_post_check' 失败分支锚点")
+
+// 从锚点向后 800 字符内应该有 return { stageCompleted: false ... }
+const tail = src.slice(failedAnchor, failedAnchor + 1200)
+const hasReturnFalse = /return\s*\{\s*stageCompleted:\s*false/.test(tail)
+check(hasReturnFalse, '失败分支末尾补 return { stageCompleted: false, ... }')
+
+// nextPendingIdx: currentIdx 字面出现（与 plan contract 一致）
+const hasNextPendingCurrent = /nextPendingIdx:\s*currentIdx/.test(tail)
+check(hasNextPendingCurrent, '失败分支返回 nextPendingIdx: currentIdx（plan contract 对齐）')
+
+// 平台模式 process.exit(1)
+const hasExitGuard = /platformOpts\.specRoot\s*\|\|\s*platformOpts\.runtimeRoot/.test(tail)
+const hasExitOne = /process\.exit\(1\)/.test(tail)
+check(hasExitGuard && hasExitOne, '失败分支含平台模式守卫 + process.exit(1)')
+
+// 验证 exit(1) 在 if 守卫内（不是裸调）—— 取 exit(1) 位置向前回溯到最近的 } 或 {
+const exitPos = tail.indexOf('process.exit(1)')
+const segmentBeforeExit = tail.slice(0, exitPos)
+const lastOpenBrace = segmentBeforeExit.lastIndexOf('{')
+const lastCloseBrace = segmentBeforeExit.lastIndexOf('}')
+check(lastOpenBrace > lastCloseBrace, 'process.exit(1) 在某个 if 块的 { ... } 内（受守卫保护）')
+
+// 验证 exit 守卫表达式在 exit 之前的同一块内
+const guardSegment = tail.slice(Math.max(0, exitPos - 300), exitPos)
+check(/platformOpts\.(specRoot|runtimeRoot)/.test(guardSegment),
+  'process.exit(1) 前的代码块内含平台模式守卫条件')
+
+// 对照 plan contract（run.js 内 plan 失败分支 return 结构）
+// 定位 plan 阶段失败分支的 stageCompleted:false return
+const planFailMatch = src.match(/plan[\s\S]{0,2000}?return\s*\{\s*stageCompleted:\s*false[\s\S]{0,200}?\}/)
+check(!!planFailMatch, 'plan contract 存在 stageCompleted:false return（对照基准）')
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+if (failed > 0) process.exit(1)

package/test/run-scan-project-parse.test.mjs

@@ -0,0 +1,200 @@
+/**
+ * scan step 2 项目列表解析 — 强契约测试
+ *
+ * 解析只接受两种结构化格式：
+ *   A) YAML block: scan_projects:\n  - id: name
+ *   B) BEGIN_PROJECT_LIST ... END_PROJECT_LIST
+ *
+ * 自由文本列表不再解析，防止误识别垃圾项目名。
+ */
+import { sanitizeProjectName, validateParsedProjects } from '../src/run.js'
+
+let passed = 0
+let failed = 0
+function assertDeepEqual (actual, expected, msg) {
+  const a = JSON.stringify(actual)
+  const e = JSON.stringify(expected)
+  if (a === e) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   expected: ${e}\n   actual:   ${a}`); failed++ }
+}
+function assertEqual (actual, expected, msg) {
+  if (actual === expected) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   expected: ${expected}\n   actual:   ${actual}`); failed++ }
+}
+function assertIncludes (str, sub, msg) {
+  if (str.includes(sub)) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}\n   expected to include: ${sub}\n   actual: ${str}`); failed++ }
+}
+
+// ---- 复刻 run.js 中新的解析逻辑 ----
+function parseProjectListFromOutput(outputText) {
+  let parsedProjects = [] // Array<{id, path?}>
+  let parsedFromStructuredOutput = false
+  if (outputText) {
+    // 格式 A: YAML block
+    const yamlBlock = outputText.match(/scan_projects:\s*\n([\s\S]+?)(?=$|\n[^\s])/)
+    if (yamlBlock) {
+      const entries = [...yamlBlock[1].matchAll(/-\s+id:\s*(\S+)(?:[\s\S]*?)(?=\n\s+-\s+id:|$)/g)]
+      for (const m of entries) {
+        const id = sanitizeProjectName(m[1])
+        if (!id) continue
+        const pathMatch = m[0].match(/path:\s*(\S+)/)
+        const entry = pathMatch ? { id, path: pathMatch[1].trim() } : { id }
+        parsedProjects.push(entry)
+      }
+      parsedFromStructuredOutput = parsedProjects.length > 0
+    }
+    // 格式 B: BEGIN_PROJECT_LIST
+    if (!parsedFromStructuredOutput) {
+      const blockMatch = outputText.match(/BEGIN_PROJECT_LIST\s*\n([\s\S]*?)\n*END_PROJECT_LIST/)
+      if (blockMatch) {
+        const raw = [...blockMatch[1].matchAll(/^-\s+(\S+)/gm)].map(m => m[1])
+        parsedProjects = raw.map(s => sanitizeProjectName(s)).filter(Boolean).map(id => ({ id }))
+        parsedFromStructuredOutput = parsedProjects.length > 0
+      }
+    }
+  }
+  return { parsedProjects, parsedFromStructuredOutput }
+}
+
+// ======== 解析测试 ========
+
+// 1. YAML block 正常解析
+assertDeepEqual(
+  parseProjectListFromOutput(`scan_projects:
+  - id: backend
+  - id: frontend
+  - id: daemon
+`).parsedProjects,
+  [{ id: 'backend' }, { id: 'frontend' }, { id: 'daemon' }],
+  'YAML block 正常解析 3 个项目'
+)
+
+// 2. YAML block 带 path 字段（多行属性）
+const r2 = parseProjectListFromOutput(`scan_projects:
+  - id: api
+    path: backend/
+  - id: web
+    path: frontend/
+`).parsedProjects
+assertDeepEqual(r2, [{ id: 'api', path: 'backend/' }, { id: 'web', path: 'frontend/' }],
+  'YAML block 带 path 字段正常解析')
+
+// 3. BEGIN_PROJECT_LIST 正常解析
+assertDeepEqual(
+  parseProjectListFromOutput(`BEGIN_PROJECT_LIST
+- backend
+- frontend
+- daemon
+END_PROJECT_LIST`).parsedProjects,
+  [{ id: 'backend' }, { id: 'frontend' }, { id: 'daemon' }],
+  'BEGIN_PROJECT_LIST 标记块正常解析'
+)
+
+// 4. 自由文本编号列表 → 不解析
+const { parsedProjects: fn, parsedFromStructuredOutput: fnParsed } =
+  parseProjectListFromOutput('扫描项目列表：\n1. scan1backendmulti-agent-platform-api FastAPI Python\n2. frontendmulti-agent-platform-web Next.js TS\n3. sillyhub-daemon Node.js TS')
+assertEqual(fnParsed, false, '自由文本编号列表不触发解析')
+assertDeepEqual(fn, [], '自由文本编号列表不产生任何项目名')
+
+// 5. 自由文本括号枚举 → 不解析
+const { parsedProjects: fn2, parsedFromStructuredOutput: fn2Parsed } =
+  parseProjectListFromOutput('子项目: backend / frontend / user-service')
+assertEqual(fn2Parsed, false, '自由文本括号枚举不触发解析')
+assertDeepEqual(fn2, [], '自由文本括号枚举不产生任何项目名')
+
+// 6. 空 outputText → 不解析
+const { parsedFromStructuredOutput: emptyParsed } = parseProjectListFromOutput('')
+assertEqual(emptyParsed, false, '空 outputText 不触发解析')
+
+// 7. 普通摘要文本 → 不解析
+const { parsedProjects: summary, parsedFromStructuredOutput: summaryParsed } =
+  parseProjectListFromOutput('确认扫描 3 个子项目：backend、frontend、daemon，全部重新扫描')
+assertEqual(summaryParsed, false, '普通摘要文本不触发解析')
+assertDeepEqual(summary, [], '普通摘要文本不产生任何项目名')
+
+// ======== validateParsedProjects — 基础校验 ========
+
+// 8. 正常列表（无 path）
+assertDeepEqual(
+  validateParsedProjects([{ id: 'backend' }, { id: 'frontend' }, { id: 'daemon' }], '/tmp/proj'),
+  { ok: true, errors: [] },
+  '正常列表校验通过（无 path）'
+)
+
+// 9. 正常列表（有合法 path）——需要用真实路径
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import os from 'os'
+const tmpDir = mkdtempSync(join(os.tmpdir(), 'sillyspec-test-'))
+mkdirSync(join(tmpDir, 'backend'))
+mkdirSync(join(tmpDir, 'frontend'))
+assertDeepEqual(
+  validateParsedProjects([
+    { id: 'backend', path: 'backend' },
+    { id: 'frontend', path: 'frontend' }
+  ], tmpDir),
+  { ok: true, errors: [] },
+  '合法 path 校验通过'
+)
+
+// 10. path 不存在 → 失败
+const v10 = validateParsedProjects([{ id: 'backend', path: 'nonexistent' }], tmpDir)
+assertEqual(v10.ok, false, 'path 不存在校验失败')
+assertIncludes(v10.errors[0], '不存在', '错误提示包含"不存在"')
+
+// 11. path 含 .. 越界 → 失败
+const v11 = validateParsedProjects([{ id: 'backend', path: '../etc/passwd' }], tmpDir)
+assertEqual(v11.ok, false, 'path 包含 .. 校验失败')
+assertIncludes(v11.errors[0], '..', '错误提示包含 ..')
+
+// 12. path 解析后超出 source_root → 失败
+const v12 = validateParsedProjects([{ id: 'backend', path: '/etc/passwd' }], tmpDir)
+assertEqual(v12.ok, false, '绝对路径超出 source_root 校验失败')
+assertIncludes(v12.errors[0], '超出', '错误提示包含"超出"')
+
+// 13. 超过 10 个项目 → 失败
+const many = Array.from({ length: 11 }, (_, i) => ({ id: `project${i}` }))
+const v13 = validateParsedProjects(many, tmpDir)
+assertEqual(v13.ok, false, '超过 10 个项目校验失败')
+assertIncludes(v13.errors[0], '超过上限', '错误提示包含"超过上限"')
+
+// 14. 重复项目名 → 失败
+const v14 = validateParsedProjects([{ id: 'backend' }, { id: 'frontend' }, { id: 'backend' }], tmpDir)
+assertEqual(v14.ok, false, '重复项目名校验失败')
+assertIncludes(v14.errors[0], '重复', '错误提示包含"重复"')
+
+// 15. 非法 slug（中文）→ 失败
+const v15 = validateParsedProjects([{ id: 'backend' }, { id: '前端服务' }], tmpDir)
+assertEqual(v15.ok, false, '非法 slug 校验失败')
+
+// 16. 空列表 → 失败
+const v16 = validateParsedProjects([], tmpDir)
+assertEqual(v16.ok, false, '空列表校验失败')
+
+// 17. null 列表 → 失败
+const v17 = validateParsedProjects(null, tmpDir)
+assertEqual(v17.ok, false, 'null 列表校验失败')
+
+// 18. 单字符 → 失败
+const v18 = validateParsedProjects([{ id: 'a' }], tmpDir)
+assertEqual(v18.ok, false, '单字符项目名校验失败')
+
+// 19. 纯数字 → 失败
+const v19 = validateParsedProjects([{ id: '123' }], tmpDir)
+assertEqual(v19.ok, false, '纯数字项目名校验失败')
+
+// 20. 兼容旧 API（纯字符串数组）
+assertDeepEqual(
+  validateParsedProjects(['backend', 'frontend'], tmpDir),
+  { ok: true, errors: [] },
+  '旧 API 兼容：纯字符串数组仍通过'
+)
+
+// 清理
+rmSync(tmpDir, { recursive: true, force: true })
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+if (failed > 0) process.exit(1)

package/test/run-tests.mjs

@@ -0,0 +1,48 @@
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execFileSync } from 'node:child_process'
+
+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)
+}
+
+let passed = 0
+let failed = 0
+const failures = []
+
+for (const file of files) {
+  const fullPath = join(testDir, file)
+  console.log(`\nRunning ${file}`)
+  try {
+    const output = execFileSync(process.execPath, [fullPath], {
+      cwd: testDir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 120_000
+    })
+    if (output) process.stdout.write(output)
+    passed++
+  } catch (err) {
+    if (err.stdout) process.stdout.write(err.stdout)
+    if (err.stderr) process.stderr.write(err.stderr)
+    failed++
+    failures.push(file)
+    console.log(`  ❌ ${file} exited with code ${err.status || 1}`)
+  }
+}
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+if (failures.length > 0) {
+  console.log(`失败文件: ${failures.join(', ')}`)
+}
+console.log(`${'='.repeat(50)}`)
+
+process.exit(failed > 0 ? 1 : 0)

package/test/scan-docs-yaml-placeholders.test.mjs

@@ -0,0 +1,84 @@
+/**
+ * task-05: scan-docs.yaml 占位符 {SPEC_ROOT} + 项目名优先级
+ *
+ * 覆盖：
+ * - AC-01: 8 处 outputs.path 均为 {SPEC_ROOT}/docs/<project>/scan/*.md
+ * - AC-02: write_scope 含 {SPEC_ROOT}/docs/<project>/scan/
+ * - AC-07: 旧 yaml（无 {SPEC_ROOT}）兼容，replace 不命中也不报错
+ */
+import { readFileSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const yamlPath = join(__dirname, '..', 'templates', 'workflows', 'scan-docs.yaml')
+const yaml = readFileSync(yamlPath, 'utf8')
+
+let passed = 0
+let failed = 0
+function assert (cond, msg) {
+  if (cond) { console.log(`✅ PASS: ${msg}`); passed++ }
+  else { console.error(`❌ FAIL: ${msg}`); failed++ }
+}
+
+// AC-01: 8 处 outputs.path 改占位符
+const expectedDocs = [
+  'ARCHITECTURE.md',
+  'CONVENTIONS.md',
+  'STRUCTURE.md',
+  'INTEGRATIONS.md',
+  'TESTING.md',
+  'CONCERNS.md',
+  'PROJECT.md',
+]
+console.log('=== AC-01: outputs.path 改占位符 {SPEC_ROOT} ===')
+for (const doc of expectedDocs) {
+  const expectedLine = `path: "{SPEC_ROOT}/docs/<project>/scan/${doc}"`
+  assert(yaml.includes(expectedLine), `outputs.path 含 {SPEC_ROOT} 占位符 → ${doc}`)
+}
+
+// AC-01 反向：不应再有硬编码 .sillyspec/docs/<project>/scan/X.md
+console.log('\n=== AC-01 反向：不再有硬编码 .sillyspec/docs/<project>/scan/ ===')
+const hardcodedMatches = yaml.match(/\.sillyspec\/docs\/<project>\/scan\//g) || []
+assert(hardcodedMatches.length === 0,
+  `outputs.path/write_scope 不再含 ".sillyspec/docs/<project>/scan/"（找到 ${hardcodedMatches.length} 处）`)
+
+// AC-02: write_scope 含 {SPEC_ROOT}
+console.log('\n=== AC-02: write_scope 含 {SPEC_ROOT} ===')
+assert(yaml.includes('- "{SPEC_ROOT}/docs/<project>/scan/"'),
+  'write_scope 含 {SPEC_ROOT}/docs/<project>/scan/')
+
+// AC-07 兼容：旧 yaml（无 {SPEC_ROOT}）replace 不命中（用代码模拟）
+console.log('\n=== AC-07: 旧 yaml 占位符兼容性 ===')
+{
+  const legacyPrompt = '写文件到 .sillyspec/docs/<project>/scan/X.md'
+  const replaced = legacyPrompt.replace(/\{SPEC_ROOT\}/g, '/tmp/spec')
+  assert(!replaced.includes('{SPEC_ROOT}'), '旧 yaml 无 {SPEC_ROOT} 字面：replace 后无残留')
+  assert(replaced.includes('.sillyspec/docs/'), '旧 yaml 行为：保留原 .sillyspec/docs/ 路径（向后兼容）')
+}
+
+// AC-03: 新 yaml 替换后路径正确
+console.log('\n=== AC-03: 新 yaml 占位符替换 ===')
+{
+  const newPrompt = '写文件到 {SPEC_ROOT}/docs/<project>/scan/X.md'
+  const step1 = newPrompt.replace(/\{SPEC_ROOT\}/g, '/tmp/spec')
+  const step2 = step1.replace(/<project>/g, 'myaaa')
+  assert(step2 === '写文件到 /tmp/spec/docs/myaaa/scan/X.md',
+    `占位符替换正确：${step2}`)
+  assert(!step2.includes('{SPEC_ROOT}'), '替换后无 {SPEC_ROOT} 残留')
+  assert(!step2.includes('<project>'), '替换后无 <project> 残留')
+}
+
+// 结构完整性：其他字段未动
+console.log('\n=== 结构完整性：其他字段未变 ===')
+assert(yaml.includes('name: scan-docs'), 'yaml name 字段保留')
+assert(yaml.includes('checks:'), 'checks 段保留')
+assert(yaml.includes('path: "scan/"'), 'workflow_level.path "scan/" 相对子路径保留（不动）')
+assert(yaml.includes('retry:'), 'retry 段保留')
+assert(yaml.includes('on_check_failure: prompt_retry'), 'on_check_failure 保留')
+assert(yaml.includes('allow_shell: true'), 'permissions.allow_shell 保留')
+
+console.log(`\n${'='.repeat(50)}`)
+console.log(`✅ 通过: ${passed}  ❌ 失败: ${failed}`)
+console.log(`${'='.repeat(50)}`)
+if (failed > 0) process.exit(1)

package/test/scan-knowledge.test.mjs

@@ -0,0 +1,175 @@
+/**
+ * scan-knowledge.test.mjs — knowledge 产物校验测试
+ */
+
+import { join, resolve, dirname, basename } from 'path'
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { fileURLToPath, pathToFileURL } from 'url'
+import { tmpdir } from 'os'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const root = resolve(__dirname, '..')
+
+const { runScanPostCheck } = await import(pathToFileURL(join(root, 'src', 'scan-postcheck.js')).href)
+
+let passed = 0, failed = 0
+
+function assert(cond, msg) {
+  if (cond) { console.log(`  ✅ PASS: ${msg}`); passed++ }
+  else { console.log(`  ❌ FAIL: ${msg}`); failed++ }
+}
+
+function setup(name) {
+  const cwd = join(tmpdir(), `kn-${name}`)
+  mkdirSync(cwd, { recursive: true })
+  return cwd
+}
+function specSetup(name) {
+  const d = join(tmpdir(), `kn-${name}-spec`)
+  mkdirSync(d, { recursive: true })
+  return d
+}
+function clean(...dirs) { for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {} }
+
+const DOCS = ['ARCHITECTURE.md','CONVENTIONS.md','STRUCTURE.md','INTEGRATIONS.md','TESTING.md','CONCERNS.md','PROJECT.md']
+
+function writeFull(cwd, specDir) {
+  const proj = basename(cwd)
+  for (const d of DOCS) {
+    const p = join(specDir, 'docs', proj, 'scan', d)
+    mkdirSync(dirname(p), { recursive: true })
+    writeFileSync(p, 'author: bot\ncreated_at: 2026-06-19 10:00:00\n# doc\n')
+  }
+}
+
+// ── 1: knowledge INDEX.md 存在，引用真实文件 → 通过 ──
+console.log('\n=== Test 1: knowledge INDEX.md 存在且引用有效 → no knowledge warning ===')
+{
+  const cwd = setup('t1'), spec = specSetup('t1')
+  try {
+    writeFull(cwd, spec)
+    const knowledgeDir = join(spec, 'knowledge')
+    mkdirSync(knowledgeDir, { recursive: true })
+    writeFileSync(join(knowledgeDir, 'INDEX.md'),
+      '# Knowledge Index\n\n## Conventions\n- [kebab-case naming](conventions.md#kebab-case-naming)\n')
+    writeFileSync(join(knowledgeDir, 'conventions.md'),
+      '# Conventions\n\n## kebab-case-naming\nFiles use kebab-case.\n')
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const knowledgeChecks = result.checks.filter(c => c.name.startsWith('knowledge_'))
+    assert(knowledgeChecks.length === 0, 'no knowledge warnings when INDEX.md + referenced files exist')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 2: knowledge 目录不存在 → dir_missing 警告 ──
+console.log('\n=== Test 2: knowledge 目录不存在 → knowledge_dir_missing ===')
+{
+  const cwd = setup('t2'), spec = specSetup('t2')
+  try {
+    writeFull(cwd, spec)
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const missing = result.checks.find(c => c.name === 'knowledge_dir_missing')
+    assert(!!missing, 'knowledge_dir_missing check exists')
+    assert(missing.detail.includes('knowledge/ 目录不存在'), 'detail text correct')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 3: INDEX.md 不存在 → index_missing 警告 ──
+console.log('\n=== Test 3: INDEX.md 不存在 → knowledge_index_missing ===')
+{
+  const cwd = setup('t3'), spec = specSetup('t3')
+  try {
+    writeFull(cwd, spec)
+    const knowledgeDir = join(spec, 'knowledge')
+    mkdirSync(knowledgeDir, { recursive: true })
+    // INDEX.md not created
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const missing = result.checks.find(c => c.name === 'knowledge_index_missing')
+    assert(!!missing, 'knowledge_index_missing check exists')
+    assert(missing.detail.includes('INDEX.md 不存在'), 'detail text correct')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 4: INDEX.md 引用不存在文件 → broken_refs 警告 ──
+console.log('\n=== Test 4: INDEX.md 引用不存在的文件 → knowledge_broken_refs ===')
+{
+  const cwd = setup('t4'), spec = specSetup('t4')
+  try {
+    writeFull(cwd, spec)
+    const knowledgeDir = join(spec, 'knowledge')
+    mkdirSync(knowledgeDir, { recursive: true })
+    writeFileSync(join(knowledgeDir, 'INDEX.md'),
+      '# Knowledge Index\n\n## Conventions\n- [naming](conventions.md#naming)\n\n## Patterns\n- [auth pattern](patterns.md#auth-pattern)\n')
+    // conventions.md exists, patterns.md does not
+    writeFileSync(join(knowledgeDir, 'conventions.md'), '# Conventions\n')
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const broken = result.checks.find(c => c.name === 'knowledge_broken_refs')
+    assert(!!broken, 'knowledge_broken_refs check exists')
+    assert(broken.detail.includes('patterns.md'), 'reports missing patterns.md')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 5: uncategorized.md 为空但存在 → 通过 ──
+console.log('\n=== Test 5: uncategorized.md 空但存在 → no knowledge warning ===')
+{
+  const cwd = setup('t5'), spec = specSetup('t5')
+  try {
+    writeFull(cwd, spec)
+    const knowledgeDir = join(spec, 'knowledge')
+    mkdirSync(knowledgeDir, { recursive: true })
+    writeFileSync(join(knowledgeDir, 'INDEX.md'),
+      '# Knowledge Index\n\n(no entries yet)\n')
+    writeFileSync(join(knowledgeDir, 'uncategorized.md'), '# Uncategorized\n')
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const knowledgeChecks = result.checks.filter(c => c.name.startsWith('knowledge_'))
+    assert(knowledgeChecks.length === 0, 'empty uncategorized.md passes')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 6: categorized 文件存在但 INDEX.md 无条目 → 通过（不强求 categorized 非空）──
+console.log('\n=== Test 6: categorized 文件存在 + INDEX.md 有效 → no knowledge warning ===')
+{
+  const cwd = setup('t6'), spec = specSetup('t6')
+  try {
+    writeFull(cwd, spec)
+    const knowledgeDir = join(spec, 'knowledge')
+    mkdirSync(knowledgeDir, { recursive: true })
+    writeFileSync(join(knowledgeDir, 'INDEX.md'),
+      '# Knowledge Index\n\n## Known Issues\n- [GLM proxy](known-issues.md#glm-proxy)\n')
+    writeFileSync(join(knowledgeDir, 'known-issues.md'),
+      '# Known Issues\n\n## glm-proxy\nGLM proxy has usage metadata limits.\n')
+    writeFileSync(join(knowledgeDir, 'uncategorized.md'), '# Uncategorized\n')
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const knowledgeChecks = result.checks.filter(c => c.name.startsWith('knowledge_'))
+    assert(knowledgeChecks.length === 0, 'at least one categorized file + valid INDEX passes')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 7: source_root knowledge 泄漏检测（平台模式已有检查）──
+console.log('\n=== Test 7: source_root knowledge 泄漏 → source_root_leak ===')
+{
+  const cwd = setup('t7'), spec = specSetup('t7')
+  try {
+    writeFull(cwd, spec)
+    // 写入 source_root/.sillyspec/knowledge/ 泄漏
+    const leakedKnowledgeDir = join(cwd, '.sillyspec', 'knowledge')
+    mkdirSync(leakedKnowledgeDir, { recursive: true })
+    writeFileSync(join(leakedKnowledgeDir, 'INDEX.md'), '# leaked\n')
+
+    const result = runScanPostCheck({ cwd, specDir: spec })
+    const leak = result.checks.find(c => c.name === 'source_root_leak')
+    assert(!!leak, 'source_root knowledge leak detected')
+    assert(leak.severity === 'failed', 'leak severity is failed')
+  } finally { clean(cwd, spec) }
+}
+
+// ── 汇总 ──
+console.log(`\n${'='.repeat(40)}`)
+console.log(`scan-knowledge tests: ${passed} passed, ${failed} failed, ${passed + failed} total`)
+if (failed > 0) process.exit(1)