sillyspec 3.29.4 → 3.31.0

package/src/init.js

@@ -5,6 +5,7 @@ import { checkbox, confirm, input } from '@inquirer/prompts';
 import { ProgressManager } from './progress.js';
 import chalk from 'chalk';
 import { getVersion } from './version.js';
+import { injectCommandCards } from './command-cards.js';
 import { gitQuiet } from './git-helper.js';
 import { renderExample } from './config-schema.js';
 // 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
@@ -76,10 +77,11 @@ function copyDirSync(src, dst) {
 
 
 
-const VALID_TOOLS = ['claude', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
+const VALID_TOOLS = ['claude', 'zcode', 'cursor', 'openclaw', 'codex', 'gemini', 'opencode'];
 
 const TOOL_LABELS = {
   claude: 'Claude Code',
+  zcode: 'ZCode',
   cursor: 'Cursor',
   openclaw: 'OpenClaw',
   codex: 'OpenAI Codex (通过 AGENTS.md)',
@@ -288,14 +290,17 @@ function isTTY() {
 
 // ── 核心安装逻辑 ──
 
-function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
+async function doInstall(projectDir, tools, subprojects = [], specDir = null, options = {}) {
   // specDir: 规范目录（默认 projectDir/.sillyspec）
   // projectDir: 源码项目根目录（用于工具检测、指令注入、.gitignore）
   // options.noSkills: 跳过 skills 复制段（--no-skills；指令注入不受影响）
   // options.platformMode: 平台模式（cmdInit 收到 platformOpts 非空）——项目内 .sillyspec/
   //   通常只有 local.yaml（平台 init lease 写、含用户手调 mcp 段），任何清理都会丢失，整体跳过
-  const { noSkills = false, platformMode = false } = options;
+  const { noSkills = false, platformMode = false, forceCards = false } = options;
   const spec = specDir || join(projectDir, '.sillyspec');
+  // 命令卡工具面（2026-09-21-flow-command-cards）：仅 zcode/claude 有落点（D-003）；
+  // noSkills/platformMode 与 skills 同门跳过（Grill P2-4）
+  const cardTools = noSkills || platformMode ? [] : tools.filter((t) => t === 'zcode' || t === 'claude');
 
   // 外部 specDir 时清理旧版本残留的 cwd/.sillyspec/（防止源码污染）。
   // ⚠️ 必须保护真实资产：若本地 .sillyspec 含 changes/（非空）、projects/（非空）
@@ -443,11 +448,23 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null, options
     }
   }
 
-  // 注入 AGENTS.md 完整指引（claude/codex 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移）
-  if (tools.includes('claude') || tools.includes('codex')) {
+  // 注入 AGENTS.md 完整指引（claude/codex/zcode 共用：版本感知幂等三态四分支 + 旧 ## SillySpec 段迁移；
+  // zcode 2026-09-21-flow-command-cards FR-05 入面——AGENTS.md 是跨工具通用标准内容源）
+  if (tools.includes('claude') || tools.includes('codex') || tools.includes('zcode')) {
     injectAgentsInstructions(projectDir);
   }
 
+  // 流程命令卡注入（2026-09-21-flow-command-cards：zcode→.zcode/commands/sillyspec/、claude→.claude/commands/sillyspec/；
+  // 尾部锚行三态幂等。与 skills 复制同门：noSkills/platformMode 跳过（工具目录零污染语义，Grill P2-4）；
+  // 挂点在 noSkills return 之前——卡与 AGENTS.md 同批，早于 skills 复制不影响）
+  if (cardTools.length > 0) {
+    const cards = await injectCommandCards(projectDir, { tools: cardTools, force: forceCards, version: getVersion() });
+    for (const w of cards.warnings) console.warn(`    ⚠️ [命令卡] ${w}`);
+    if (cards.written.length + cards.updated.length > 0) {
+      console.log(chalk.green(`    ✓ 流程命令卡已${cards.written.length ? '生成' : '更新'} ${cards.written.length + cards.updated.length} 张 → ${cardTools.map((t) => (t === 'zcode' ? '.zcode' : '.claude') + '/commands/sillyspec/').join(' + ')}`));
+    }
+  }
+
   // 注入 CLAUDE.md 指针（claude 专属：@AGENTS.md 导入薄文件，须在 AGENTS.md 之后）
   if (tools.includes('claude')) {
     injectClaudePointer(projectDir);
@@ -546,7 +563,7 @@ function showSummary(version, tools, specDir) {
 // ── 主命令 ──
 
 export async function cmdInit(projectDir, options = {}) {
-  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, platformOpts = null } = options;
+  const { tool, tools: toolsOpt, interactive, specDir, noSkills = false, forceCards = false, platformOpts = null } = options;
   const version = getVersion();
   const resolvedSpecDir = specDir ? resolve(specDir) : null;
 
@@ -654,7 +671,7 @@ export async function cmdInit(projectDir, options = {}) {
     }
 
     console.log('');
-    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+    await doInstall(projectDir, selectedTools, subprojects, resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
     writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
     showSummary(version, selectedTools, resolvedSpecDir);
     return;
@@ -682,7 +699,7 @@ export async function cmdInit(projectDir, options = {}) {
     tools = detectTools(projectDir);
   }
 
-  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, platformMode: platformOpts != null });
+  await doInstall(projectDir, tools, [], resolvedSpecDir, { noSkills, forceCards, platformMode: platformOpts != null });
   writeInitPlatformPointer(projectDir, resolvedSpecDir, platformOpts);
 
   console.log('');

package/src/knowledge-classify.js

@@ -101,7 +101,7 @@ function resolveKeywords(keywords, title) {
  * @returns {{ start: number, end: number, headingText: string, qlIdPrefix: string|null,
  *             title: string, body: string, text: string }[]}
  */
-function parseUncategorizedEntries(normalizedContent) {
+export function parseUncategorizedEntries(normalizedContent) {
   const lines = normalizedContent.split('\n')
   const boundaryRe = /^#{1,3}\s+\S/
   const entryHeadingRe = /^#{2,3}\s+\S/
@@ -380,3 +380,49 @@ export async function cmdKnowledgeClassify(dir, args, opts = {}) {
     }, result.error)
   }
 }
+
+/**
+ * `sillyspec knowledge inbox` 子命令——知识收件箱按需视图（2026-09-23 知识可见性 quick）。
+ *
+ * 背景：uncategorized 待审条目与 quick 资产尾蒸馏产出此前只落文件、不在聊天面露头，
+ * 用户全程无感（2026-09-23 用户反馈「聊天过程中完全不知道」）。收件箱给出待审清单
+ * （标题 + ql 前缀 + 一行摘要）与基线状态；--json 结构化供面板/脚本消费。纯读零副作用。
+ */
+export async function cmdKnowledgeInbox(dir, args, opts = {}) {
+  const base = opts.specDir || join(dir, '.sillyspec')
+  const knowledgeDir = join(base, 'knowledge')
+  const wantJson = args.includes('--json')
+  const uncPath = join(knowledgeDir, 'uncategorized.md')
+  let entries = []
+  if (existsSync(uncPath)) {
+    entries = parseUncategorizedEntries(readFileSync(uncPath, 'utf8').replace(/\r\n/g, '\n'))
+  }
+  let baseline = null
+  try {
+    const bp = join(base, 'knowledge-baseline')
+    if (existsSync(bp)) {
+      const n = parseInt(readFileSync(bp, 'utf8').trim(), 10)
+      if (Number.isFinite(n) && n >= 0) baseline = n
+    }
+  } catch { /* 基线读失败按未启用 */ }
+  const over = baseline !== null && entries.length > baseline
+  const items = entries.map((e) => ({
+    title: e.title,
+    qlId: e.qlIdPrefix || null,
+    summary: String(e.body || '').replace(/\s+/g, ' ').slice(0, 80),
+  }))
+  if (wantJson) {
+    output(true, { inbox: { count: entries.length, baseline, over, items } })
+    return
+  }
+  if (entries.length === 0) {
+    console.log('📚 知识收件箱：空——uncategorized 无待审条目')
+    return
+  }
+  console.log(`📚 知识收件箱：待审 ${entries.length} 条${baseline !== null ? `（基线 ${baseline}${over ? '，已超 ⚠️' : ''}）` : ''}`)
+  items.forEach((it, i) => {
+    console.log(`  ${i + 1}. 《${it.title}》${it.qlId ? `（${it.qlId}）` : ''}`)
+    if (it.summary) console.log(`     ${it.summary}`)
+  })
+  console.log('   归类：sillyspec knowledge classify --title "…" --file conventions|patterns|known-issues.md')
+}

package/src/knowledge-digest.js

@@ -0,0 +1,162 @@
+/**
+ * knowledge-digest.js — 知识资产治理信号收集器（2026-09-27-knowledge-digest）
+ *
+ * 现状：通用知识走 propose→平台人工合并闭环，规格资产（FR 索引/绑定）全自动入库零人审——
+ * 四类信号沉睡库内无人工出口（R23-full 载体仓收件箱积压 40 条实证）。本模块把沉睡数据
+ * 变结构化摘要：`sillyspec knowledge digest`（人读文本）/ `--json`（平台 RPC 消费）。
+ *
+ * 四信号（阈值内静默、超阈才进摘要——安静即健康态，防仪式化）：
+ *   ① rot 待复核标记：knowledge/fr/*.md 条目内「待复核：」行，按域计数（阈值 100）
+ *   ② 收件箱积压：knowledge/uncategorized.md 的 `## <qlId> | <标题>` 条目（阈值 20）
+ *   ③ 伪域落库：auto-* 域文件条目数 + unmapped 池条目数（阈值 0——伪域本不该增长）
+ *   ④ 绑定路径解析失败：fr/*.md 绑定行经 resolveTestFileRel（与 repair-paths/门禁读侧
+ *      同口径单源）无法自仓根解析（阈值 0）
+ *
+ * 只读扫描，零写入——动作（迁移/清账/repair）由消费方另行执行。
+ */
+import { existsSync, readFileSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { readFrBindings, resolveTestFileRel, testAnchorFile } from './test-bindings.js'
+
+/** 伪域判定：auto- 前缀（scaffold 时代机器蒸馏域）或 unmapped 池 */
+const isPseudoDomain = (domain) => /^auto[-_]/.test(domain) || domain === 'unmapped'
+
+/** 交付路径 → 建议域（落域机械改进的建议器，与 indexRequirements 的告警共用单源） */
+export function suggestDomainFromFiles(files) {
+  for (const raw of files || []) {
+    const p = String(raw || '').replace(/\\/g, '/')
+    let m
+    if ((m = /^backend\/app\/modules\/([\w-]+)\//.exec(p))) return m[1] // backend 模块归属最强
+    if ((m = /^sillyhub-daemon\//.exec(p))) return 'daemon'
+    if ((m = /^frontend\//.exec(p))) return 'frontend'
+    if ((m = /^backend\//.exec(p))) return 'backend'
+    if ((m = /^([\w-]+)\/src\//.exec(p))) return m[1]
+    if ((m = /^([\w-]+)\//.exec(p))) return m[1]
+  }
+  return null
+}
+
+/** 条目级解析：fr/<域>.md 的 `## <id> <标题>` 段头与「待复核：」行 */
+function scanFrFile(text) {
+  const entries = []
+  let cur = null
+  for (const line of text.split(/\r?\n/)) {
+    const h = /^## (FR-[\w.-]+-\d+|FR-\d+)\s*(.*)$/.exec(line)
+    if (h) { cur = { id: h[1], needsReview: null }; entries.push(cur); continue }
+    if (cur) {
+      const r = /^待复核：(.+)$/.exec(line)
+      if (r) cur.needsReview = r[1].trim()
+    }
+  }
+  return entries
+}
+
+/**
+ * 收集治理信号（纯函数，只读）。
+ * @returns {{ generated_at: string, healthy: boolean, signals: Array<{kind, level, title, count, detail, suggestion?}>, totals: object }}
+ */
+export function collectKnowledgeDigest({ specBase, projectRoot }) {
+  const knowledgeRoot = join(specBase, 'knowledge')
+  const frDir = join(knowledgeRoot, 'fr')
+  const signals = []
+  const totals = { rot: 0, inbox: 0, pseudo: 0, unresolvedBindings: 0 }
+
+  const rotByDomain = new Map()
+  const pseudoByDomain = new Map()
+  const unresolved = []
+  const frFiles = existsSync(frDir) ? readdirSync(frDir).filter(f => f.endsWith('.md')).sort() : []
+  // unmapped 基线消音（与 fr-index 落库告警同口径）：跨仓历史基线不刷信号，只报增量
+  let unmappedBaseline = 0
+  try {
+    const raw = readFileSync(join(specBase, 'local.yaml'), 'utf8')
+    const m = raw.match(/^fr_unmapped_baseline:\s*(\d+)\s*$/m)
+    if (m) unmappedBaseline = parseInt(m[1], 10)
+  } catch { /* 无 local.yaml = 无基线 */ }
+
+  for (const f of frFiles) {
+    const domain = f.replace(/\.md$/, '')
+    const text = readFileSync(join(frDir, f), 'utf8')
+    const entries = scanFrFile(text)
+    const rot = entries.filter(e => e.needsReview).length
+    if (rot > 0) { rotByDomain.set(domain, rot); totals.rot += rot }
+    if (isPseudoDomain(domain) && entries.length > 0) {
+      // 基线内的 unmapped 池不计（历史跨仓基线，非新增堆积）；auto-* 伪域无基线语义恒计
+      const count = domain === 'unmapped' ? Math.max(0, entries.length - unmappedBaseline) : entries.length
+      if (count > 0) { pseudoByDomain.set(domain, count); totals.pseudo += count }
+    }
+    // 绑定解析失败（与 repair-paths 同口径：先根相对直取，再 resolveTestFileRel）
+    for (const e of entries) {
+      const rows = readFrBindings({ knowledgeRoot, frId: e.id })
+      for (const row of rows) {
+        for (const t of row.tests || []) {
+          // 锚剥离单源（评审 P1 清偿）：testAnchorFile 吃全部分隔形态（#/::/「」/>）——
+          // 手搓 split('#').split('::') 漏「」锚致 7/8 假阳性（目标文件全在场），与 repair-paths 口径对拍实证
+          const filePart = testAnchorFile(String(t))
+          const rel = resolveTestFileRel(filePart, { projectRoot })
+          if (!rel && !existsSync(join(projectRoot, filePart.replace(/\\/g, '/')))) {
+            totals.unresolvedBindings++
+            unresolved.push(`${e.id}:${t}`)
+          }
+        }
+      }
+    }
+  }
+
+  // ② 收件箱（uncategorized.md 的 `## <qlId> | <标题>` 行）
+  let inboxTitles = []
+  const uncPath = join(knowledgeRoot, 'uncategorized.md')
+  if (existsSync(uncPath)) {
+    inboxTitles = readFileSync(uncPath, 'utf8').split(/\r?\n/)
+      .map(l => /^## (.+)$/.exec(l)?.[1]).filter(Boolean)
+    totals.inbox = inboxTitles.length
+  }
+
+  const mk = (kind, level, title, count, detail, suggestion) =>
+    signals.push({ kind, level, title, count, detail, ...(suggestion ? { suggestion } : {}) })
+
+  if (totals.rot > 100) {
+    mk('rot', 'warn', `rot 待复核批量标记（${totals.rot} 条 > 100）`, totals.rot,
+      [...rotByDomain.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([d, n]) => `${d} ${n}`).join('、'),
+      '批量复核：文案漂移类可批量承接，行为类逐条对账')
+  }
+  if (totals.inbox > 20) {
+    mk('inbox', 'warn', `知识收件箱积压（${totals.inbox} 条 > 20）`, totals.inbox,
+      inboxTitles.slice(0, 5).join('；') + (inboxTitles.length > 5 ? ' 等' : ''),
+      'sillyspec knowledge inbox 逐条 classify 清账')
+  }
+  if (totals.pseudo > 0) {
+    mk('pseudo-domain', 'warn', `伪域在库（auto-*/unmapped 共 ${totals.pseudo} 条）`, totals.pseudo,
+      [...pseudoByDomain.entries()].map(([d, n]) => `${d} ${n}`).join('、'),
+      '按 suggestDomainFromFiles 建议迁移域（平台信号卡一键/手工 redomain）')
+  }
+  if (totals.unresolvedBindings > 0) {
+    mk('binding-unresolved', 'warn', `绑定路径解析失败（${totals.unresolvedBindings} 个）`, totals.unresolvedBindings,
+      unresolved.slice(0, 5).join('、') + (unresolved.length > 5 ? ' 等' : ''),
+      'sillyspec tests repair-paths（干跑预览 → --write 归一）')
+  }
+
+  return {
+    generated_at: new Date().toISOString(),
+    healthy: signals.length === 0,
+    signals,
+    totals,
+  }
+}
+
+/** 人读文本渲染（CLI 出口；平台走 --json） */
+export function renderKnowledgeDigestText(d) {
+  const lines = []
+  lines.push(`📬 知识资产治理摘要（${d.generated_at.slice(0, 16).replace('T', ' ')}）`)
+  if (d.healthy) {
+    lines.push('✅ 四类信号全部在阈内（rot/inbox/伪域/坏绑定）——安静即健康态，无需动作')
+  } else {
+    lines.push(`⚠️ ${d.signals.length} 类信号超阈：`)
+    for (const s of d.signals) {
+      lines.push(`  [${s.kind}] ${s.title}`)
+      if (s.detail) lines.push(`     明细：${s.detail}`)
+      if (s.suggestion) lines.push(`     处置：${s.suggestion}`)
+    }
+  }
+  lines.push(`底数：rot 待复核 ${d.totals.rot}｜收件箱 ${d.totals.inbox}｜伪域条目 ${d.totals.pseudo}｜坏绑定 ${d.totals.unresolvedBindings}`)
+  return lines.join('\n')
+}

package/src/knowledge-quicklog.js

@@ -0,0 +1,246 @@
+/**
+ * knowledge-quicklog.js — quicklog 历史检索面（知识可见性导线）
+ *
+ * 缺口（2026-09-21 R5R 实证）：quick 产出（quicklog 条目 + patch）不在任何检索面——
+ * knowledge-match 只扫 INDEX 路由与 decisions；主仓唯一核验过键名的先例
+ * （ql-20260920-007-d0dd）因 linked 变更未归档而 distill 缺席，FR 检索面零覆盖，
+ * 后续三个独立会话全部猜错同一外部键。本模块把 quicklog 历史拉进注入面：
+ * 纯读、fail-open、top-3 一行制——注入的是「发生过什么」的历史事实（条目说的是
+ * 当时做了什么），不是权威断言；消费方要用契约细节按 ql-ID 回源读全文或读代码。
+ *
+ * 与 knowledge-match.js 分工：那边消费 INDEX/decisions（结构化知识），这边消费双信号源——
+ * quicklog/QUICKLOG-*.md（append-only 历史）+ changes/archive/<变更>/flow-state.yaml（flow 族归档
+ * 变更伪条目，2026-09-23 扩源：flow 变更不产生 quicklog 条目，扩源后检索面才看得见）。
+ * 条目头与字段行是 allocateQuicklogEntry
+ * 的机械解析契约：`## ql-<id> | <时间> | <标题>` + `文件：` 段（`- path（注记）` 行）。
+ * run/prompt.js（execute 确认步 + quick step1）与 stages/execute.js（Wave 孪生）两处
+ * 注入点共用本模块——格式等价由 test/knowledge-inject.test.mjs 锁定，改渲染必同步两处。
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+
+const QUICKLOG_ENTRY_RE = /^##\s+(ql-[\w-]+)\s*\|\s*([^|]+)\s*\|\s*(.+)$/
+// 文件注记行：`- path（中文括注）` / `- path(ascii)` / 裸 `- path`（allocateQuicklogEntry
+// 均可产出；path 本身不含空白，故止于首个空白或括号）
+const QUICKLOG_FILE_LINE_RE = /^-\s+([^\s（(]+)/
+// 文件：段结束边界——出现其他字段标签行即收段（状态/需求/根因/方案/结果/审计/关联变更）
+const QUICKLOG_FIELD_RE = /^(状态|关联变更|需求|根因|方案|结果|审计)\s*[：:]/
+
+/**
+ * 解析 quicklog 全量条目——双信号源（资产三小件①，2026-09-23 扩源）：
+ *   ① quicklog/QUICKLOG-*.md（append-only 历史条目，含按日归档的分片文件）；
+ *   ② .sillyspec/changes/archive/<变更>/flow-state.yaml（flow 族归档变更）——flow 变更不产生
+ *      quicklog 条目，检索面此前看不见 flow 变更的知识（与 ql-011 治的病同族）。伪条目
+ *      三料合成：qlId=变更目录名 / date=目录名日期前缀（缺前缀退 flow-state.yaml mtime）/
+ *      title=proposal.md 首个 `# ` 标题行（缺文件退变更名）；solution 恒空、files 恒空。
+ * 双源命中时 quicklog 条目排前（matchQuicklogContext 排序 source 键）。
+ * @param {string} specBase - .sillyspec 根
+ * @returns {{ qlId: string, date: string, title: string, solution: string, files: string[], source: 'quicklog'|'flow' }[]}
+ *   两源都不存在 / 全部不可读 → []（调用方零注入零阻断）
+ */
+export function parseQuicklogEntries(specBase) {
+  return [...parseQuicklogFileEntries(specBase), ...parseFlowArchiveEntries(specBase)]
+}
+
+/** 源①：quicklog/QUICKLOG-*.md 条目解析（原 parseQuicklogEntries 主体，行为不变）。 */
+function parseQuicklogFileEntries(specBase) {
+  const dir = join(specBase, 'quicklog')
+  let files
+  try {
+    files = readdirSync(dir).filter((f) => /^QUICKLOG-.*\.md$/i.test(f))
+  } catch {
+    return []
+  }
+  const entries = []
+  for (const f of files) {
+    let content
+    try {
+      content = readFileSync(join(dir, f), 'utf8')
+    } catch {
+      continue
+    }
+    let cur = null
+    let inFiles = false
+    const flush = () => {
+      if (cur) entries.push(cur)
+      cur = null
+    }
+    for (const line of content.replace(/\r\n/g, '\n').split('\n')) {
+      const h = line.match(QUICKLOG_ENTRY_RE)
+      if (h) {
+        flush()
+        cur = { qlId: h[1].trim(), date: h[2].trim(), title: h[3].trim(), solution: '', files: [], source: 'quicklog' }
+        inFiles = false
+        continue
+      }
+      if (!cur) continue
+      if (QUICKLOG_FIELD_RE.test(line)) {
+        inFiles = false
+        const m = line.match(/^方案\s*[：:]\s*(.*)$/)
+        if (m) cur.solution = m[1].trim()
+        continue
+      }
+      if (/^文件\s*[：:]/.test(line)) {
+        inFiles = true
+        continue
+      }
+      if (inFiles) {
+        const m = line.match(QUICKLOG_FILE_LINE_RE)
+        if (m) cur.files.push(m[1].replace(/\\/g, '/'))
+      }
+    }
+    flush()
+  }
+  return entries
+}
+
+/** 源②：flow 归档变更伪条目——目录内 flow-state.yaml 在场即认（不校验 yaml 内容：伪条目
+ * 只需「这曾是一个 flow 变更」的存在信号，字段全来自目录名与 proposal.md，缺件逐项降级）。 */
+function parseFlowArchiveEntries(specBase) {
+  const archiveDir = join(specBase, 'changes', 'archive')
+  let dirs
+  try {
+    dirs = readdirSync(archiveDir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const out = []
+  for (const d of dirs) {
+    if (!d.isDirectory()) continue
+    try {
+      const dir = join(archiveDir, d.name)
+      if (!existsSync(join(dir, 'flow-state.yaml'))) continue
+      const dm = d.name.match(/^(\d{4}-\d{2}-\d{2})-/)
+      let date = dm ? dm[1] : ''
+      if (!date) {
+        try { date = new Date(statSync(join(dir, 'flow-state.yaml')).mtime).toISOString().slice(0, 10) } catch { /* mtime 不可得 → 空日期（排序自然靠后） */ }
+      }
+      let title = ''
+      try {
+        const prop = readFileSync(join(dir, 'proposal.md'), 'utf8')
+        const h = prop.replace(/\r\n/g, '\n').split('\n').find((l) => /^#\s+/.test(l))
+        if (h) title = h.replace(/^#\s+/, '').trim()
+      } catch { /* 无 proposal.md → 标题退变更名 */ }
+      out.push({ qlId: d.name, date, title: title || d.name, solution: '', files: [], source: 'flow' })
+    } catch { /* 单目录读取异常 → 跳过该目录（fail-open，不影响其余源） */ }
+  }
+  return out
+}
+
+// ── 匹配打分 ─────────────────────────────────────────────────────────────────
+// 查询侧 token：ASCII 词（≥3 字符，词边界匹配）+ CJK 连续段（≥2 字，子串匹配）——
+// 与 knowledge-match.keywordMatchesContext 同判法，方向相反（那边条目出关键词查上下文，
+// 这边上下文出 token 查条目——quicklog 条目没有 INDEX 关键词行，只能反向）。
+const ASCII_TOKEN_RE = /[a-z][a-z0-9._-]{2,}/g
+const CJK_RUN_RE = /[\u4e00-\u9fff]{2,}/g
+
+function contextTokens(taskContext) {
+  const s = String(taskContext || '').toLowerCase()
+  const out = new Set()
+  for (const t of s.match(ASCII_TOKEN_RE) || []) out.add(t)
+  for (const t of s.match(CJK_RUN_RE) || []) out.add(t)
+  return [...out]
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** 文件命中权重：路径/文件名是强信号（同一文件被改过 ≈ 同域修补） */
+const FILE_HIT_WEIGHT = 5
+/** 命中门槛：≥1 文件命中，或 ≥2 个不同 token 命中（单 token 命中多为噪音词，不注入） */
+const MIN_TOKEN_HITS = 2
+
+/** 源排序权重：quicklog 条目 0（排前），flow 伪条目 1——双源命中时 quicklog 优先（更新鲜）。 */
+function sourceRank(entry) {
+  return entry && entry.source === 'flow' ? 1 : 0
+}
+
+/**
+ * 任务上下文 × quicklog 条目匹配（双源条目统一打分，排序 source 键优先）。
+ * @param {string} specBase - .sillyspec 根
+ * @param {string} taskContext - 任务描述串（与 matchKnowledge 的 query 同源）
+ * @param {{ limit?: number }} [opts] - 注入上限（默认 3）
+ * @returns {{ hits: Array<{ qlId: string, date: string, title: string, files: string[] }>, report: string }}
+ *   无 quicklog / 无命中 / 任何异常 → { hits: [], report: '' }（fail-open，永不抛）
+ */
+export function matchQuicklogContext(specBase, taskContext, { limit = 3 } = {}) {
+  try {
+    if (!specBase || !taskContext) return { hits: [], report: '' }
+    const entries = parseQuicklogEntries(specBase)
+    if (entries.length === 0) return { hits: [], report: '' }
+    const tokens = contextTokens(taskContext)
+    if (tokens.length === 0) return { hits: [], report: '' }
+
+    const scored = []
+    for (const e of entries) {
+      const hay = [e.title, e.solution, e.files.join(' ')].join(' ').toLowerCase()
+      const basenames = new Set(e.files.map((f) => f.split('/').pop().toLowerCase()))
+      let score = 0
+      let tokenHits = 0
+      let fileHit = 0
+      for (const t of tokens) {
+        let hit = false
+        if (/[^\x00-\x7f]/.test(t)) {
+          hit = hay.includes(t)
+        } else {
+          hit = new RegExp(`(^|[^a-z0-9])${escapeRegex(t)}([^a-z0-9]|$)`).test(hay)
+          if (!hit && t.length >= 4) {
+            for (const b of basenames) {
+              if (b.includes(t)) {
+                hit = true
+                fileHit++
+                score += FILE_HIT_WEIGHT
+                break
+              }
+            }
+          }
+        }
+        if (hit) {
+          score += 1
+          tokenHits++
+        }
+      }
+      if (fileHit >= 1 || tokenHits >= MIN_TOKEN_HITS) {
+        scored.push({ entry: e, score, fileHit })
+      }
+    }
+    scored.sort((a, b) =>
+      (sourceRank(a.entry) - sourceRank(b.entry)) ||
+      (b.fileHit - a.fileHit) ||
+      (b.score - a.score) ||
+      String(b.entry.date).localeCompare(String(a.entry.date))
+    )
+    const top = scored.slice(0, Math.max(1, limit)).map((s) => ({
+      qlId: s.entry.qlId,
+      date: String(s.entry.date).slice(0, 10),
+      title: s.entry.title,
+      files: s.entry.files,
+    }))
+    return { hits: top, report: renderQuicklogSection(top) }
+  } catch {
+    return { hits: [], report: '' }
+  }
+}
+
+/**
+ * 注入段渲染（prompt.js 与 execute.js 孪生共用——仅段头层级不同）。
+ * 一行一条：ql-ID · 标题（截 60）· 日期 · 至多 2 个触碰文件。零正文注入——
+ * quicklog 条目正文可能很长，注入面只做「知道有这回事 + 回源指针」。
+ * @param {Array<{qlId,date,title,files}>} hits
+ * @param {{ h3?: boolean }} [opts] - execute.js Wave prompt 内用 h3（### ）对齐知识段层级
+ */
+export function renderQuicklogSection(hits, { h3 = false } = {}) {
+  if (!Array.isArray(hits) || hits.length === 0) return ''
+  const lines = [
+    `${h3 ? '### ' : ''}🕘 近期 quick 修补（quicklog 机械匹配，top-${hits.length}——历史记录非权威断言，细节按 ql-ID 回源 .sillyspec/quicklog/ 或读代码）`,
+  ]
+  for (const h of hits) {
+    const files = (h.files || []).slice(0, 2).join(', ')
+    const title = String(h.title || '').slice(0, 60)
+    const date = String(h.date || '').slice(0, 10)
+    lines.push(` - ${h.qlId} · ${title} · ${date}${files ? ` · ${files}` : ''}`)
+  }
+  return lines.join('\n')
+}