sillyspec 3.27.2 → 3.27.6

package/.worktrees/8d2d0392/src/check-primitives.js

@@ -0,0 +1,65 @@
+/**
+ * check-primitives.js — 共享的产物字面校验原语(纯函数)
+ *
+ * 从 workflow.js 的 checkOutput / _checkWorkflow 抽出,作为"何谓 contains_sections / min_lines /
+ * no_placeholder / no_empty_files"的**全仓单一语义源**。workflow 引擎与 stage-contract 引擎
+ * (stage-contract-engine.js)共用同一组谓词,杜绝"workflow 认 `## X` 子串、stage-contract 认别的"
+ * 这类判定分叉(本任务的"事前==事后"同源在原语层就成立)。
+ *
+ * 设计原则:纯文本判定,不碰 fs。调用方负责读文件 + CRLF 归一化后传入 content——
+ * 这样 Windows CRLF 差异在调用方收敛(plan-postcheck 已用 LF-normalizing reader),引擎拿到
+ * 什么判什么,不在原语层二次引入 readFileSync 差异(缺陷 windows-python-crlf-taskcard 的根因)。
+ */
+
+// no_placeholder 的默认占位词。与原 workflow.js checkOutput/_checkWorkflow 逐字一致——
+// 改动会破坏存量扫描文档的占位判定,属契约级常量。
+const DEFAULT_PLACEHOLDER_PATTERNS = [
+  '待补充', 'TODO', 'TBD', '未分析', '根据项目情况', '根据实际情况', '按需填写',
+]
+
+/** 内容非空(trim 后有字符)。用于 no_empty_files。 */
+export function contentNonEmpty(content) {
+  return typeof content === 'string' && content.trim().length > 0
+}
+
+/** 行数(split('\n'))。用于 min_lines 的 detail 文案与判定。 */
+export function lineCount(content) {
+  return typeof content === 'string' ? content.split('\n').length : 0
+}
+
+/** 行数 ≥ min。用于 min_lines 判定。 */
+export function meetsMinLines(content, min) {
+  return lineCount(content) >= min
+}
+
+/**
+ * 返回缺失的章节(sections 中未以 `## <section>` 子串出现的)。
+ * 用于 contains_sections——判定与原 workflow.js 逐字一致(`## ${s}` 前缀子串匹配)。
+ */
+export function missingSections(content, sections) {
+  if (typeof content !== 'string') return sections.slice()
+  return sections.filter(s => !content.includes(`## ${s}`))
+}
+
+/** 是否含全部章节(missingSections 为空的语法糖)。 */
+export function hasAllSections(content, sections) {
+  return missingSections(content, sections).length === 0
+}
+
+/**
+ * 返回命中的占位词(patterns 中匹配"独立成行"的)。
+ * 用于 no_placeholder——正则 `^\s*[-*]?\s*<p>\s*$`(m flag)与原 workflow.js 逐字一致。
+ * patterns 为空/未传时用 DEFAULT_PLACEHOLDER_PATTERNS(等价原 `check.patterns || [defaults]`)。
+ */
+export function placeholderLineMatches(content, patterns) {
+  if (typeof content !== 'string') return []
+  const pats = (patterns && patterns.length > 0) ? patterns : DEFAULT_PLACEHOLDER_PATTERNS
+  return pats.filter(p => new RegExp(`^\\s*[-*]?\\s*${p}\\s*$`, 'm').test(content))
+}
+
+/** 无占位词命中(placeholderLineMatches 为空的语法糖)。 */
+export function hasNoPlaceholderLine(content, patterns) {
+  return placeholderLineMatches(content, patterns).length === 0
+}
+
+export { DEFAULT_PLACEHOLDER_PATTERNS }

package/.worktrees/8d2d0392/src/classify-change.js

@@ -0,0 +1,109 @@
+/**
+ * classify-change.js — 变更规模分类器
+ *
+ * 将用户需求描述分类为 quick / auto / full，
+ * 供 auto 模式决定内部流程深度。
+ */
+
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import jsYaml from 'js-yaml'
+
+/**
+ * 用户显式指定的关键词 → 强制模式
+ */
+const FORCE_FULL_PATTERNS = [
+  /数据库|database|schema/i,
+  /迁移|migration|migrate/i,
+  /鉴权|权限|auth|permission|rbac/i,
+  /支付|payment|billing/i,
+  /重构|refactor.*architectur/i,
+  /微服务|microserv/i,
+]
+
+const FORCE_QUICK_PATTERNS = [
+  /fix typo/i,
+  /更新文案|改文案|文案修改/i,
+  /样式调整|style.*tweak/i,
+  /修复.*\s*\bbug\b.*\bfix\b/i,
+]
+
+/**
+ * 读 local.yaml 的 auto_mode 段（best-effort，绝不抛）。
+ * 供 runCommand 接线：传给 classifyChange 的 localConfig，让 force_*_patterns 真生效。
+ * @param {string} cwd - 主仓库根（local.yaml 在 <cwd>/.sillyspec/local.yaml）
+ * @returns {{ force_full_patterns?: string[], force_quick_patterns?: string[] } | null}
+ *   auto_mode 段含至少一个 string pattern → 归一化数组；文件缺/解析失败/无段/空 → null（降级默认关键词）
+ */
+export function readAutoModeFromLocalYaml(cwd) {
+  try {
+    const p = join(cwd, '.sillyspec', 'local.yaml')
+    if (!existsSync(p)) return null
+    const doc = jsYaml.load(readFileSync(p, 'utf8'))
+    if (!doc || typeof doc !== 'object') return null
+    const am = doc.auto_mode
+    if (!am || typeof am !== 'object') return null
+    const ffp = Array.isArray(am.force_full_patterns) ? am.force_full_patterns.filter(s => typeof s === 'string') : []
+    const fqp = Array.isArray(am.force_quick_patterns) ? am.force_quick_patterns.filter(s => typeof s === 'string') : []
+    if (ffp.length === 0 && fqp.length === 0) return null
+    return { force_full_patterns: ffp, force_quick_patterns: fqp }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 分类变更规模
+ * @param {object} opts
+ * @param {string} opts.description - 用户需求描述
+ * @param {string} [opts.explicitMode] - 用户显式指定的模式（auto/quick/full）
+ * @param {object} [opts.localConfig] - local.yaml auto_mode 段（由 readAutoModeFromLocalYaml 读出）
+ * @returns {{ mode: 'quick'|'auto'|'full', reason: string }}
+ */
+export function classifyChange({ description = '', explicitMode, localConfig } = {}) {
+  // 1. 用户显式指定优先级最高
+  if (explicitMode && ['quick', 'auto', 'full'].includes(explicitMode)) {
+    return { mode: explicitMode, reason: '用户显式指定' }
+  }
+
+  // 2. local.yaml force patterns
+  if (localConfig) {
+    const forceFullPatterns = localConfig.force_full_patterns || []
+    const forceQuickPatterns = localConfig.force_quick_patterns || []
+
+    for (const pattern of forceFullPatterns) {
+      try {
+        if (new RegExp(pattern, 'i').test(description)) {
+          return { mode: 'full', reason: `local.yaml force_full_pattern 匹配: ${pattern}` }
+        }
+      } catch {
+        // 非法正则跳过，不崩 auto 分类（review-2026-08-09 #30）
+      }
+    }
+    for (const pattern of forceQuickPatterns) {
+      try {
+        if (new RegExp(pattern, 'i').test(description)) {
+          return { mode: 'quick', reason: `local.yaml force_quick_pattern 匹配: ${pattern}` }
+        }
+      } catch {
+        // 非法正则跳过
+      }
+    }
+  }
+
+  // 3. 默认关键词匹配
+  for (const pattern of FORCE_QUICK_PATTERNS) {
+    if (pattern.test(description)) {
+      return { mode: 'quick', reason: `命中 quick 关键词: ${pattern.source}` }
+    }
+  }
+
+  for (const pattern of FORCE_FULL_PATTERNS) {
+    if (pattern.test(description)) {
+      return { mode: 'full', reason: `命中 full 关键词: ${pattern.source}` }
+    }
+  }
+
+  // 4. 默认 auto
+  return { mode: 'auto', reason: '默认模式' }
+}

package/.worktrees/8d2d0392/src/commit-suggest.js

@@ -0,0 +1,202 @@
+/**
+ * commit-suggest.js — `sillyspec commit` 的语义收集 + commit message 建议生成
+ * （2026-08-21 agent-手工产出审计第二批 G1-G3）。
+ *
+ * commit skill 此前让 agent 手工收集语义：取 LAST_COMMIT_TIME、cat 多处 QUICKLOG、
+ * 扫变更目录、按时间戳过滤已勾 task、按路径模式识别来源阶段——进度库/quicklog/
+ * git 全在 CLI 手里，这是「CLI 有数据却让 agent 重新收集」的最典型案例。
+ *
+ * 本模块一条命令产出全部上下文 + conventional commits 建议 message + 可照抄的
+ * git commit 命令。**只建议不执行**（对齐 skill 绝对规则「不要自动提交」——确认权在人）。
+ *
+ * 语义来源（与 skill 手工流程同源）：
+ *   A. QUICKLOG：specBase/quicklog/QUICKLOG-<user>.md + changes/<change>/quicklog/ 下的归属条目，
+ *      条目时间 > 上次 commit 时间者（首次提交全收）
+ *   B. execute 已勾 task：活跃变更 tasks.md 的 [x] 行（tasks.md mtime > 上次 commit 才计入，
+ *      防旧变更全勾 task 永久污染建议）
+ *   C. 阶段产出：changed paths 按路径模式归 scan/brainstorm/plan/execute/archive/knowledge
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+import { gitQuiet } from './git-helper.js'
+import { resolveSpecDir } from './run/shared.js'
+
+function listActiveChanges(specBase) {
+  try {
+    return readdirSync(join(specBase, 'changes'), { withFileTypes: true })
+      .filter(e => e.isDirectory() && e.name !== 'archive')
+      .map(e => e.name)
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 解析 QUICKLOG 文件里的条目（## ql-xxx | time | title + 状态：行）
+ */
+function parseQuicklogEntries(file) {
+  let content
+  try {
+    content = readFileSync(file, 'utf8')
+  } catch {
+    return []
+  }
+  const entries = []
+  const lines = content.split('\n')
+  let cur = null
+  for (const line of lines) {
+    const h = line.match(/^## (ql-\S+) \| ([0-9: -]+?) \| (.*)$/)
+    if (h) {
+      if (cur) entries.push(cur)
+      cur = { qlId: h[1], time: h[2].trim(), title: h[3].trim(), status: '未知' }
+      continue
+    }
+    if (cur) {
+      const s = line.match(/^状态[：:]\s*(\S+)/)
+      if (s) cur.status = s[1]
+    }
+  }
+  if (cur) entries.push(cur)
+  return entries
+}
+
+function classifyStagePath(p) {
+  const posix = p.replace(/\\/g, '/')
+  if (/^\.sillyspec\/docs\/[^/]+\/scan\//.test(posix)) return 'scan'
+  if (/^\.sillyspec\/changes\/archive\//.test(posix)) return 'archive'
+  if (/^\.sillyspec\/changes\/[^/]+\/(proposal|design)\.md/.test(posix)) return 'brainstorm'
+  if (/^\.sillyspec\/changes\/[^/]+\/(tasks|plan)\.md/.test(posix)) return 'plan'
+  if (/^\.sillyspec\/knowledge\//.test(posix)) return 'knowledge'
+  return null
+}
+
+/**
+ * 收集提交上下文并生成建议 message。
+ * @param {{ cwd: string, specDir?: string|null }} opts
+ * @returns {{
+ *   lastCommitTime: string|null, hasChanges: boolean, changedCount: number, stat: string,
+ *   quickEntries: Array<{qlId,time,title,status,file}>, checkedTasks: Array<{change,item}>,
+ *   stageArtifacts: string[], suggestion: {type, subject, body}|null
+ * }}
+ */
+export function collectCommitContext({ cwd, specDir = null }) {
+  const specBase = resolveSpecDir(cwd, { specDir })
+  const lastCommitTime = gitQuiet(cwd, ['log', '-1', '--format=%ci'])
+  const lastCommitKey = lastCommitTime ? lastCommitTime.slice(0, 19) : null
+
+  // -uall：未跟踪目录不折叠（.sillyspec/ 整体未跟踪时默认 porcelain 只给一行 `?? .sillyspec/`，
+  // 路径模式分类会瞎；-uall 逐文件列出，scan/brainstorm/plan 分类才有输入）
+  const porcelain = gitQuiet(cwd, ['status', '--porcelain', '-uall']) || ''
+  const changedLines = porcelain.split('\n').filter(Boolean)
+  const changedPaths = changedLines.map(l => l.slice(3).trim()).filter(Boolean)
+  const untrackedCount = changedLines.filter(l => l.startsWith('??')).length
+  const stat = gitQuiet(cwd, ['diff', 'HEAD', '--stat']) || (changedPaths.length > 0 ? `（${changedPaths.length} 个文件待首提交）` : '')
+
+  // ── 来源 A：QUICKLOG（主 quicklog + 各活跃变更归属 quicklog）──
+  const quickFiles = []
+  try {
+    for (const f of readdirSync(join(specBase, 'quicklog'))) {
+      if (/^QUICKLOG.*\.md$/.test(f)) quickFiles.push(join(specBase, 'quicklog', f))
+    }
+  } catch {}
+  for (const c of listActiveChanges(specBase)) {
+    try {
+      for (const f of readdirSync(join(specBase, 'changes', c, 'quicklog'))) {
+        if (f.endsWith('.md')) quickFiles.push(join(specBase, 'changes', c, 'quicklog', f))
+      }
+    } catch {}
+  }
+  const quickEntries = quickFiles
+    .flatMap(file => parseQuicklogEntries(file).map(e => ({ ...e, file })))
+    .filter(e => !lastCommitKey || e.time > lastCommitKey)
+    .sort((a, b) => (a.time < b.time ? -1 : 1))
+  const doneQuick = quickEntries.filter(e => e.status === '已完成')
+
+  // ── 来源 B：活跃变更已勾 task（tasks.md mtime 晚于上次 commit 才计入）──
+  const lastCommitMs = lastCommitTime ? Date.parse(lastCommitTime) : null
+  const checkedTasks = []
+  for (const c of listActiveChanges(specBase)) {
+    const tasksPath = join(specBase, 'changes', c, 'tasks.md')
+    if (!existsSync(tasksPath)) continue
+    if (lastCommitMs !== null && !Number.isNaN(lastCommitMs)) {
+      try {
+        // epoch 对比（非字符串）：git %ci 带本地时区偏移，Date.parse 归一；字符串对比会因
+        // UTC/本地时差把刚改过的 tasks.md 误判为早于上次 commit 而漏收
+        if (statSync(tasksPath).mtime.getTime() <= lastCommitMs) continue
+      } catch { continue }
+    }
+    for (const line of readFileSync(tasksPath, 'utf8').split('\n')) {
+      const m = line.match(/^[-*]\s*\[[xX]\]\s*(task-\d+)\s*[:：]?\s*(.*)/)
+      if (m) checkedTasks.push({ change: c, item: `${m[1]}: ${m[2].trim()}` })
+    }
+  }
+
+  // ── 来源 C：阶段产出（changed paths 按模式归类去重）──
+  const stageSet = new Set()
+  for (const p of changedPaths) {
+    const stage = classifyStagePath(p)
+    if (stage) stageSet.add(stage)
+  }
+  const stageArtifacts = [...stageSet]
+
+  // ── 建议 message（对齐 commit skill 的 type 表）──
+  let suggestion = null
+  const bodyLines = []
+  const hasQuick = doneQuick.length > 0
+  const hasTasks = checkedTasks.length > 0
+  const hasStages = stageArtifacts.length > 0
+
+  if (hasQuick || hasTasks || hasStages) {
+    let type
+    let subject
+    if (hasTasks && !hasQuick) {
+      type = 'feat'
+      const byChange = new Map()
+      for (const t of checkedTasks) {
+        if (!byChange.has(t.change)) byChange.set(t.change, [])
+        byChange.get(t.change).push(t.item)
+      }
+      const [firstChange, items] = [...byChange][0]
+      subject = `feat: ${firstChange} 完成 task ×${items.length}`
+    } else if (hasQuick && !hasTasks) {
+      type = 'fix'
+      if (doneQuick.length === 1) {
+        subject = `fix: ${doneQuick[0].title}`
+      } else if (doneQuick.length === 2) {
+        subject = `fix: ${doneQuick[0].title}；${doneQuick[1].title}`
+      } else {
+        subject = `fix: quick 修复 ${doneQuick.length} 项`
+      }
+    } else if (hasTasks) {
+      type = 'feat'
+      subject = `feat: 变更交付 + quick 修复 ${doneQuick.length} 项`
+    } else {
+      type = 'fix'
+      subject = `fix: quick 修复 + 阶段产出`
+    }
+    if (doneQuick.length >= 2 || hasTasks || hasStages) {
+      for (const q of doneQuick) bodyLines.push(`- quick ${q.qlId}: ${q.title}`)
+    }
+    for (const t of checkedTasks) bodyLines.push(`- ${t.change} ${t.item}`)
+    for (const s of stageArtifacts) bodyLines.push(`- 阶段产出: ${s}`)
+    if (!hasStages && !hasTasks && doneQuick.length === 1) bodyLines.length = 0
+    suggestion = {
+      type,
+      subject: subject.length > 100 ? subject.slice(0, 100) + '…' : subject,
+      body: bodyLines.length > 0 ? bodyLines.join('\n') : '',
+    }
+  }
+
+  return {
+    lastCommitTime,
+    hasChanges: changedPaths.length > 0,
+    changedCount: changedPaths.length,
+    untrackedCount,
+    stat,
+    quickEntries,
+    checkedTasks,
+    stageArtifacts,
+    suggestion,
+  }
+}

package/.worktrees/8d2d0392/src/config-cat.js

@@ -0,0 +1,88 @@
+/**
+ * config-cat.js — local.yaml 实际值读取的权威路径解析器（`sillyspec config cat` 数据源）。
+ *
+ * 背景（2026-08-21 root-local-yaml 治理）：`config schema` 只列键不含值，agent 拿实际配置
+ * 只能翻文件——worktree 内 `.sillyspec/` 是 checkout 副本，gitignored 的 local.yaml 不随
+ * checkout 出现，agent 找不到就漂去项目根乱找甚至乱建。cat 按「文件存在」解析真实路径，
+ * agent 不需要知道文件在哪。
+ *
+ * 候选链（首个「文件存在」者胜）：
+ * 1. specBase（--spec-dir / 平台 pointer / resolveSpecDir 祖先链首个 .sillyspec 目录）——
+ *    resolveSpecDir 按「目录存在」命中，worktree 内会停在副本目录，文件并不在那里；
+ * 2. cwd 祖先链逐级 <dir>/.sillyspec/local.yaml——worktree 副本无此文件会继续向上命中主仓
+ *    （sillyspec worktree 恒挂在 <主仓>/.sillyspec/.runtime/worktrees/ 下，祖先链必达）；
+ * 3. git common-dir 反推主仓根——用户手动 `git worktree add` 到任意位置时的兜底。
+ *
+ * 候选链不含项目根 <dir>/local.yaml——那里从来没有这个文件（hook 同步拦写）。
+ * 纯只读；平台 pointer 异常由调用方吞掉走祖先链（真实 reader 各自 fail-closed，cat 是
+ * 只读便利口，不必加重）。
+ */
+import { existsSync } from 'fs'
+import { join, resolve, dirname } from 'path'
+import { gitQuiet } from './git-helper.js'
+
+/**
+ * 解析真实 local.yaml 路径。
+ * @param {string} dir 起点目录（CLI --dir / cwd）
+ * @param {{ specBase?: string|null }} [opts] specBase = resolvePlatformSpecDir 预解析结果（可 null）
+ * @returns {{ exists: boolean, path: string|null, source: string|null, searched: string[] }}
+ *   searched 为候选链前几个路径（未命中时供人看「找过哪里」，最多 6 条）
+ */
+export function resolveLocalYaml(dir, opts = {}) {
+  const start = resolve(dir || process.cwd())
+  const seen = new Set()
+  const candidates = []
+  const push = (p, source) => {
+    const key = resolve(p)
+    if (seen.has(key)) return
+    seen.add(key)
+    candidates.push({ path: key, source })
+  }
+
+  if (opts.specBase) push(join(opts.specBase, 'local.yaml'), 'spec 根（--spec-dir/平台 pointer/最近 .sillyspec）')
+  for (let d = start; ; d = dirname(d)) {
+    push(join(d, '.sillyspec', 'local.yaml'), 'cwd 祖先链（worktree 内向上命中主仓）')
+    const parent = dirname(d)
+    if (parent === d) break
+  }
+  // git 兜底：linked worktree 内 --git-common-dir 指向主仓共享 .git，dirname 即主仓根
+  const commonDir = gitQuiet(start, ['rev-parse', '--git-common-dir'])
+  if (commonDir) {
+    const mainRoot = dirname(resolve(start, String(commonDir).trim()))
+    push(join(mainRoot, '.sillyspec', 'local.yaml'), 'git common-dir 反推主仓根')
+  }
+
+  const hit = candidates.find(c => existsSync(c.path))
+  return {
+    exists: !!hit,
+    path: hit ? hit.path : null,
+    source: hit ? hit.source : null,
+    searched: candidates.slice(0, 6).map(c => c.path),
+  }
+}
+
+/**
+ * 写侧目标解析（`sillyspec local register-repo` 用）：已存在 local.yaml → 就地更新该文件
+ * （含 worktree → 主仓解析）；全不存在 → 取 specBase（或 cwd 链）候选，但候选落在 worktree
+ * 副本下（<主仓>/.sillyspec/.runtime/worktrees/ 内）时重定向 git common-dir 主仓根——
+ * local.yaml 是 gitignored 不随 worktree checkout，写进副本目录是死配置。
+ *
+ * @param {string} dir 起点目录
+ * @param {{ specBase?: string|null }} [opts]
+ * @returns {{ path: string, existed: boolean }}
+ */
+export function resolveLocalYamlWriteTarget(dir, opts = {}) {
+  const r = resolveLocalYaml(dir, opts)
+  if (r.exists) return { path: r.path, existed: true }
+  const start = resolve(dir || process.cwd())
+  const preferred = opts.specBase ? join(opts.specBase, 'local.yaml') : join(start, '.sillyspec', 'local.yaml')
+  const posix = resolve(preferred).replace(/\\/g, '/')
+  if (posix.includes('/.sillyspec/.runtime/worktrees/')) {
+    const commonDir = gitQuiet(start, ['rev-parse', '--git-common-dir'])
+    if (commonDir) {
+      const mainRoot = dirname(resolve(start, String(commonDir).trim()))
+      return { path: join(mainRoot, '.sillyspec', 'local.yaml'), existed: false }
+    }
+  }
+  return { path: resolve(preferred), existed: false }
+}