sillyspec 3.30.0 → 3.32.0

package/src/stages/plan.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
+import jsYaml from 'js-yaml'
 import { getRule } from '../stage-contract-spec.js'
 import { REVIEW_CHECKLISTS } from '../stage-review-checklist.js'
 
@@ -414,6 +415,20 @@ execute/verify 阶段会按实际代码变更更新此文档；archive 阶段会
  */
 export function buildCoordinatorStep(changeDir, taskNames) {
   const changeName = path.basename(changeDir)
+  // 填卡 batch 阈值项目化（2026-10-06-verify-docs-prefill task-03）：「task 总数 ≤N 主 agent 直填」
+  // 原硬编码 8——430 万 token 填卡实证后按项目体系可调（local.yaml plan.fill_batch_min_tasks，
+  // integer ≥1，非法/缺省回退 8）。specBase 自 changeDir 推导（changes/<名> 的父目录）。
+  const fillBatchMin = (() => {
+    try {
+      const specBase = String(changeDir || '').replace(/[\\/]+changes[\\/]+[^\\/]+$/, '')
+      if (!specBase || specBase === changeDir) return 8
+      const p = path.join(specBase, 'local.yaml')
+      if (!existsSync(p)) return 8
+      const doc = jsYaml.load(readFileSync(p, 'utf8'))
+      const v = doc && doc.plan ? Number(doc.plan.fill_batch_min_tasks) : NaN
+      return Number.isInteger(v) && v >= 1 ? v : 8
+    } catch { return 8 }
+  })()
   const taskList = taskNames.map(t => {
     const num = t.num
     return `- task-${num}: ${t.name}`
@@ -496,8 +511,8 @@ ${taskList}
    幂等，已存在的卡跳过不覆盖；骨架带 LF 行尾 + 闭合 frontmatter + 硬校验 9 字段 + depends_on 反填。**只有主 agent 跑这一次，子代理一律不再运行 taskcard CLI。**
 1. 确认 \`${changeDir}/tasks/\` 目录存在（上一步预生成会自动创建）
 2. **默认主 agent 自己填卡（P0-2，2026-09-20 对撞实验驱动——6 个填卡子代理 6.7M token 做的是主 agent 可自完成的誊写，独立性价值为零）：**
-   - task 总数 ≤8 或变更单仓单模块 → 主 agent 逐卡 Edit 填充（骨架已预生成，誊写近乎免费），**不派子代理**
-   - 仅当 task 总数 >8 **且**跨多模块/跨仓、或主会话上下文已明显吃紧时，才按 batch 分派子代理（此时并行省墙钟有真实收益）
+   - task 总数 ≤${fillBatchMin} 或变更单仓单模块 → 主 agent 逐卡 Edit 填充（骨架已预生成，誊写近乎免费），**不派子代理**
+   - 仅当 task 总数 >${fillBatchMin} **且**跨多模块/跨仓、或主会话上下文已明显吃紧时，才按 batch 分派子代理（此时并行省墙钟有真实收益）
 3. **（分派形态时）按 batch 分派子代理（减少总子代理数量，而不是一个 task 一个子代理）：**
    - 把任务按「同一 Wave + 同一模块/相近能力 + 无跨 batch 强依赖」原则分组
    - **每个 batch 包含 2~4 个 task**；Wave 内任务数 ≤4 时整个 Wave 可作为一个 batch
@@ -508,6 +523,11 @@ ${taskList}
 5. 每个子代理使用下方「批量 TaskCard 子代理 prompt」，一次生成该 batch 的全部 task-N.md
 6. 等待所有 batch 子代理完成
 7. 验证每个 task-N.md 文件已生成且非空
+8. **全部卡片填充完成后，主 agent 跑一次零成本自检（plan 门禁同源规则前置暴露，免 Step 4 门禁批量报错返工）**：
+   \`\`\`
+   sillyspec taskcard ${changeName} --validate
+   \`\`\`
+   报错即门禁报错（frontmatter YAML/占位符/必要字段/target_files 形态，YAML 错误带中文分诊动作）；修复后重跑至通过再进下一步。
 
 > 设计意图：plan.md 里 task 数可以较多（能力拆分完整），但 TaskCard 生成阶段的**默认形态是主 agent 直填**——卡是 design/plan 的誊写不是创作，主 agent 刚写完 plan 上下文最热；子代理只在规模/上下文压力真实存在时才有净收益（每个子代理都要重读 design+plan+源码，6 个子代理 6.7M token 的实证教训）。分派时合并 batch，避免子代理数量随 task 数线性爆炸。
 

package/src/stages/verify.js

@@ -164,7 +164,8 @@ export const definition = {
 2. 如果存在：
    - 逐个读取 tasks/task-NN.md，对照 frontmatter 的 \`acceptance:\` 列表逐条核验（TaskCard 协议的验收标准在 frontmatter YAML，正文无 checkbox）
    - 每条 acceptance 对照实际实现/测试结果判定满足与否，未满足的项列为不通过
-   - 覆盖对账走探针 7 矩阵：verify-result.md「探针 7：验收×测试覆盖矩阵」段已由 CLI 预填归属测试文件与关键词提示（骨架未生成时先跑 \`sillyspec verify-probes --change <change-name> --init\`，幂等不覆盖已有正文）；逐行填判定（covered/covered-service/partial/uncovered/non-testable 五选一——covered-service 适用：端点行为由 service 层等非端点层测试锁定，证据附测试锚点）与证据——covered/covered-service/partial 附测试锚点（file:line / \`.test.\` 测试文件名 / 反引号包裹的路径或测试名，行号可省），non-testable 写一句理由；判定/证据未填会被 verify \`--done\` 门禁阻断（fail-closed）
+   - 覆盖对账走探针 7 矩阵：verify-result.md「探针 7：验收×测试覆盖矩阵」段已由 CLI 预填归属测试文件与关键词提示（骨架未生成时先跑 \`sillyspec verify-probes --change <change-name> --init\`，幂等不覆盖已有正文）；逐行填判定（covered/covered-service/partial/uncovered/non-testable 五选一——covered-service 适用：端点行为由 service 层等非端点层测试锁定，证据附测试锚点）与证据——covered/covered-service/partial 附测试锚点（file:line / \`.test.\` 测试文件名 / 反引号包裹的路径或测试名，行号可省），non-testable 写一句理由；判定/证据未填会被 verify \`--done\` 门禁阻断（fail-closed）；矩阵里带「既有用例候选（FR 关联回归面）」注记的测试是本变更未改动的既有回归用例——复核其覆盖性后如实填判定，命中≠结论
+   - **收口前预检（免逐轮撞门）**：verify-result.md 各节填完后、跑 \`--done\` 前，先跑 \`sillyspec gate verify --change <change-name> --docs-only\`——秒级只读预检纯文档契约缺项（visual-evidence/结论槽/移交项结构化等一次列清，不执行测试）；缺项清零后再走 \`--done\` 的完整实测门
 3. 如果不存在：跳过此步骤
 
 ### 输出

package/src/task-review.js

@@ -1015,7 +1015,7 @@ export function stampExecuteRunChange(runtimeRoot, runId, changeName) {
  * 读 run 目录的 change 归属戳。
  * @returns {string|null} 戳内容（trim 后非空），无戳/读失败返回 null
  */
-function readExecuteRunChangeStamp(runtimeRoot, runId) {
+export function readExecuteRunChangeStamp(runtimeRoot, runId) {
   try {
     const c = readFileSync(join(runtimeRoot, 'execute-runs', runId, 'change'), 'utf8').trim()
     return c || null

package/src/task-tick.js

@@ -0,0 +1,121 @@
+/**
+ * task-tick.js — `sillyspec task tick` 轻量勾选动词（2026-10-03-voluntary-task-tick）。
+ *
+ * 定位：让「边干边勾」成为最顺手路径——做完一个任务单元，一条命令翻格并立即拿到机器
+ * 确认（进度 N/M + 下一任务指针）。翻格产生的 tasks.md 变更由 watcher 既有 task-done
+ * 事件链实时上平台——闭环确认是 OpenSpec apply 循环「勾后重询」的本地对等物（2026-10-03
+ * local-usage-caliber-fix 0/12 事故的自愿路径修复：正反馈替代验证强制）。
+ *
+ * 事件直写（2026-10-07-thin-tasks-v3）：翻格成功后向本变更 watcher 事件流追加分级精确
+ * task-done 事件（source:'task-tick'，checked N→M 逐格口径）——watcher 3s 轮询对快速连续
+ * tick 只能采样出合并跳，收口节奏门以 CLI 精确事件为权威去重（detectBatchCheckCadence）。
+ * best-effort：事件写失败不阻断翻格（节奏门退回采样判，fail 方向安全）。
+ *
+ * 边界：
+ *   - 纯簿记动词：无 review/verdict/ownership 仪式（与 task done 四合一的分界——那是厚档
+ *     任务卡的收尾件；本动词对 thin 工作分解面与覆写面同样适用，自愿使用不违 D-007）。
+ *   - 幂等：已勾再勾走 already 分支（exit 0，零事件直写）——并发/重放零副作用；写盘走 writeAtomicSync。
+ *   - 行内替换只动 checkbox 态字符，其余字节（含 CRLF）逐字保留。
+ *   - 归档件只读：变更已归档时拒收（exit 2）。
+ */
+import { existsSync, readFileSync, appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 任务行（宽容缩进/星号有序标记，与哨兵判集行锚同口径 + 缩进容差）。 */
+const TASK_ROW_RE = /^(\s*[-*] \[)( |x|X)(\] task-(\d+):)(.*)$/
+
+/** 归一 task id：task-1 → task-01（与 governance-autopilot 勾选 token 归一同口径）。 */
+export function normalizeTaskId(id) {
+  const m = /^task-(\d+)$/.exec(String(id || '').trim())
+  return m ? `task-${String(Number(m[1])).padStart(2, '0')}` : null
+}
+
+/** 任务行清单（行序即文档序）：[{id, checked, desc}]。 */
+function collectRows(md) {
+  const rows = []
+  for (const line of String(md || '').split(/\r?\n/)) {
+    const m = line.match(TASK_ROW_RE)
+    if (m) rows.push({ id: `task-${String(Number(m[4])).padStart(2, '0')}`, checked: m[2].toLowerCase() === 'x', desc: (m[5] || '').trim() })
+  }
+  return rows
+}
+
+/**
+ * 纯函数：翻格 + 进度回显材料。
+ * @param {{tasksMd:string, taskId:string}} opts
+ * @returns {{kind:'ticked'|'already', tasksMd:string, checked:number, total:number, next:{id:string,desc:string}|null}
+ *   |{kind:'unknown', available:string[]}}
+ */
+export function tickTasksMd({ tasksMd, taskId }) {
+  const id = normalizeTaskId(taskId)
+  if (!id) return { kind: 'unknown', available: [] }
+  const rows = collectRows(tasksMd)
+  const target = rows.find((r) => r.id === id)
+  if (!target) return { kind: 'unknown', available: rows.map((r) => r.id) }
+  let out = String(tasksMd || '')
+  if (!target.checked) {
+    const re = new RegExp(`^(\\s*[-*] \\[) (\\] ${id}:)`, 'm')
+    out = out.replace(re, '$1x$2')
+  }
+  const after = collectRows(out)
+  const checked = after.filter((r) => r.checked).length
+  const pending = after.find((r) => !r.checked)
+  return {
+    kind: target.checked ? 'already' : 'ticked',
+    tasksMd: out,
+    checked,
+    total: after.length,
+    next: pending ? { id: pending.id, desc: pending.desc } : null,
+  }
+}
+
+/**
+ * IO 编排（index.js 分派入口）：定位变更目录 → tickTasksMd → 原子写盘 → 回显。
+ * exit 0=翻格/幂等；exit 2=未知 id / 缺 tasks.md / 已归档。
+ */
+export async function runTaskTick({ changeName, cwd, taskId, specBase }) {
+  const changesRoot = join(specBase, 'changes')
+  const tasksPath = join(changesRoot, changeName, 'tasks.md')
+  if (!existsSync(tasksPath)) {
+    if (existsSync(join(changesRoot, 'archive', changeName))) {
+      console.error(`❌ 变更 ${changeName} 已归档——归档件只读，不勾选`)
+    } else {
+      console.error(`❌ 未找到 ${tasksPath}——task tick 面向在途变更的任务注册表（确认 --change）`)
+    }
+    process.exit(2)
+  }
+  const r = tickTasksMd({ tasksMd: readFileSync(tasksPath, 'utf8'), taskId })
+  if (r.kind === 'unknown') {
+    const ids = (r.available || []).join('、') || '（tasks.md 无任务行）'
+    console.error(`❌ tasks.md 中无 ${taskId}——可选任务：${ids}`)
+    process.exit(2)
+  }
+  if (r.kind === 'ticked') {
+    const { writeAtomicSync } = await import('./fs-atomic.js')
+    writeAtomicSync(tasksPath, r.tasksMd)
+    // 事件直写（2026-10-07-thin-tasks-v3）：精确单格跳进事件流，节奏门按 source 去重采样合并跳。
+    try {
+      const { resolveRuntimeRoot } = await import('./run/shared.js')
+      const runtimeRoot = resolveRuntimeRoot({}, specBase)
+      const eventsPath = join(runtimeRoot, `watcher-events-${changeName}.jsonl`)
+      const from = Math.max(0, r.checked - 1)
+      appendFileSync(eventsPath, JSON.stringify({
+        ts: Date.now(), kind: 'task-done', stage: 'tasks',
+        detail: `checked ${from}→${r.checked}`, provisional: true, source: 'task-tick',
+      }) + '\n', 'utf8')
+    } catch { /* 事件 best-effort：写失败翻格不受影响（节奏门退回采样判） */ }
+    // 工件即时重推（2026-10-07-allticked-gate-docs-resync）：翻格即任务面变更——顺带触发
+    // spec-sync，平台不再停留 start 时点快照（真实会话实证：改写后平台恒显初稿）。best-effort。
+    try {
+      const { triggerSync } = await import('./run/shared.js')
+      await triggerSync(cwd, changeName, { specRoot: specBase })
+    } catch { /* 重推 best-effort：失败不影响翻格主流程 */ }
+  }
+  const nextTip = r.next
+    ? `｜下一任务：${r.next.id} ${r.next.desc.slice(0, 40)}${r.next.desc.length > 40 ? '…' : ''}`
+    : `｜🎉 ${r.total}/${r.total} 全勾——可收口：sillyspec flow done --change ${changeName}`
+  console.log(`${r.kind === 'ticked' ? '✅ 已勾' : 'ℹ️ 已是勾选态（幂等跳过写盘）'}（${r.checked}/${r.total}）${nextTip}`)
+  return r
+}
+
+export default { tickTasksMd, runTaskTick, normalizeTaskId }

package/src/taskcard-frontmatter.js

@@ -55,3 +55,34 @@ export function parseTaskFrontmatter(content) {
   }
   return { ok: true, hasFrontmatter: true, fm, error: null }
 }
+
+/**
+ * js-yaml 报错分诊（2026-10-06-verify-friction-fix task-03）：消息 + 出错行内容双信号映射中文
+ * 修复动作。背景：分诊知识长期躺在 templates/prompts/taskcard-rules.md L19-23 未接进门禁报错，
+ * 厚流程实证 agent 连撞 6 轮 YAML 门禁；且 js-yaml v4 真实消息与文档措辞有漂移（实证
+ * `title: A: B` 报 bad indentation 而非 mapping values），只匹配消息文本不可靠——先看出错行
+ * 的首字符是否保留指示符，再看行内是否「冒号+空格」，消息文本作家族归类兜底。
+ * @param {string} message js-yaml 异常 message（单行化后）
+ * @param {string} [errorLineText] 出错行原文（文件 1 基行内容；缺省只按消息分诊）
+ * @returns {string} 中文修复动作（非空）
+ */
+export function diagnoseTaskYamlError(message, errorLineText = '') {
+  const msg = String(message || '')
+  const line = String(errorLineText || '').replace(/\r$/, '')
+  // 剥列表项/缩进前缀后看首个 token 字符：反引号/@/% 是 YAML 保留指示符，js-yaml 对其报的
+  // 消息家族不稳定（实测反引号列表项报 bad indentation of a sequence entry），行内容才是可靠信号
+  const itemBody = line.replace(/^\s*(?:-\s*)?/, '')
+  if (/^[`@%]/.test(itemBody)) {
+    return '列表项/值以 YAML 保留指示符开头（反引号 `、@、%）——行首加普通文字前缀（如「执行 」）或给整行值加单引号包裹'
+  }
+  if (/quoted scalar/i.test(msg)) return '引号不成对——补齐成对引号，或改用中文引号/去掉引号'
+  if (/duplicated mapping key/i.test(msg)) return '同一字段写了两次——保留正确一处删除其余（骨架已反填的键勿重复手填）'
+  if (/expected ',' or ']'/i.test(msg)) return '方括号流序列内有裸特殊字符——改块式列表（键名换行后每项一行「  - 路径」）；空 [] 占位不受影响'
+  if (/expected ',' or '}'/i.test(msg)) return '花括号且内部含冒号或引号（JS 对象/模板字面量）——改用不含这些字符的中文描述'
+  if (/mapping values are not allowed|bad indentation/i.test(msg)) {
+    if (/: /.test(line)) return '值含「冒号+空格」（如 A: B、url: http://x）被当成嵌套映射键——去掉冒号后的空格（写 A:B）或改写为不含「: 」的中文描述'
+    return '缩进或映射结构错——块式列表项保持两空格缩进、与上级键名对齐；值含「: 」时改写描述'
+  }
+  if (/cannot start any token/i.test(msg)) return '行内含 YAML 无法起始 token 的字符（如反引号/@ 开头）——加文字前缀或用引号包裹该值'
+  return '值含特殊字符——给值加单引号、去掉「: 」冒号空格，或改块式列表（规则全表见 templates/prompts/taskcard-rules.md）'
+}

package/src/ui-visual.js

@@ -23,10 +23,13 @@ export const UI_EVIDENCE_FILENAME = 'visual-evidence.md'
 
 /* ── 检测启发式（正反例单测锁定；误判面=默认档一行警告，误漏面由文件面扩展名兜底）── */
 
+// 词表不含后端高频通用词「渲染/组件/样式」：CLI「渲染输出」「组件」「输出样式」是常规后端
+// 用语，2026-10-05-knowledge-stats-freshness 实测误触整段 UI 须知+探针 warn（描述该问题的
+// input 自己也复触一次）；真 UI 信号由页面/前端/UI/视觉/界面/布局等词与扩展名兜底承接。
 const UI_TOUCH_PATTERNS = [
-  /页面/, /前端/, /\bUI\b/i, /视觉/, /样式/, /界面/, /布局/, /主题色/, /配色/,
+  /页面/, /前端/, /\bUI\b/i, /视觉/, /界面/, /布局/, /主题色/, /配色/,
   /\.tsx?\b/, /\.jsx\b/, /\.vue\b/, /\.svelte\b/, /\.css\b/, /\.scss\b/, /\.html\b/,
-  /组件/, /原型/, /截图/, /渲染/,
+  /原型/, /截图/,
 ]
 
 /** input/规约文本是否触及前端页面或 UI（关键词启发式，≥1 命中即算）。 */
@@ -47,12 +50,16 @@ export function detectUiTouchInPaths(paths) {
 
 export function buildUiGuidanceLines() {
   return [
-    `🎨 UI 变更执行须知（本变更触及前端页面或 UI——检测命中即插入，advisory 引导非门禁）：`,
-    `   1. 改前确认视觉基准：原型产物、黄金页或该页现有截图——没有基准的「改好看」无法验收；`,
-    `   2. 边改边渲染对照：每完成一个页面任务单元就渲染实页与基准并排比对，差异清零再勾任务；`,
-    `   3. 证据随手落盘：对照截图与结论逐页记入变更目录 ${UI_EVIDENCE_FILENAME}（干活时顺手写，收口只验在场）；`,
+    `🎨 UI 变更执行须知（本变更触及前端页面或 UI——advisory 引导非门禁）：`,
+    `   1. 定稿原型必须是可复跑的真码产物（与实现同方言、能被本项目工具链构建）——手绘单文件`,
+    `      仅限一次性粗选对比，不作为交付原型（2026-09-28 frontend-apple-style 实证：手绘定稿后每条意见都要反向翻译回真实代码）；`,
+    `   2. 开工先就近发现本项目原型管线：查本次变更触达项目自己的脚本、任务与工具链（多项目仓`,
+    `      按触达路径就近，不假设全仓共享一套）；已有则复用，没有则现场搭最小管线并把入口留在`,
+    `      项目惯例位置——下一个会话能自己发现；`,
+    `   3. 边改边渲染对照：每完成一个页面任务单元就渲染实页与基准并排比对，差异清零再勾任务；`,
+    `      对照截图与结论随手落变更目录 ${UI_EVIDENCE_FILENAME}（干活时顺手写，收口只验在场）；`,
     `   4. 视觉降级须用户裁决留痕：执行中因约束对不齐基准而降级（结构收敛、范围缩小、样式统一级）`,
-    `      必须带对比截图停下找用户签字，裁决记录写进 ${UI_EVIDENCE_FILENAME}（含「用户裁决」字样段）——`,
+    `      必须停下找用户签字，裁决记录写进 ${UI_EVIDENCE_FILENAME}（含「用户裁决」字样段）——`,
     `      静默降级会在收口被「UI 视觉证据」探针硬拦（error 门）。`,
   ]
 }
@@ -70,7 +77,13 @@ export function readUiVisualGate(specBase) {
   }
 }
 
-const DOWNGRADE_LINE = /(降级|样式统一级|partial)/
+// 降级声明判定词=绑定窗口而非裸词「降级」：裸词在后端/机制讨论语境高频（探针档位、性能
+// 降级），与远处视觉词同行共现时分属两个讨论对象——2026-10-05-uivisual-word-narrow 实测
+// 「error 档（降级无裁决）……渲染/组件/样式」同行共现被误判、error 档阻断收口（自举陷阱）。
+// 窗口语义：降级与视觉词 ≤6 字内同短语（两侧顺序皆认，经既有正例「视觉收敛降级」标定）；
+// 绑定词表与 VISUAL_LINE 同集（含页面——评审 P2：缺页面时「六个页面降级为三个」漏判）；
+// 样式统一级独立短语与 \bpartial\b 词边界保留。纯结构判定，D-003 封闭面不变。
+const DOWNGRADE_LINE = /((视觉|样式|界面|页面|UI)[^\n]{0,6}降级|降级[^\n]{0,6}(视觉|样式|界面|页面|UI)|样式统一级|\bpartial\b)/i
 const VISUAL_LINE = /(视觉|UI|页面|样式|界面)/
 
 /** design/requirements 是否声明「视觉降级」（同行共现口径——行级命中防跨行误配；runUiVisualProbe 内部消费）。 */
@@ -138,6 +151,28 @@ export function runUiVisualProbe({ changeDir, gate = 'warn' }) {
   }
 }
 
+/**
+ * execute 收口的前置 advisory（2026-10-07-flow-friction-batch3 task-05）：UI 触达变更的
+ * visual-evidence.md 应在执行期随手落盘，但执法只在 verify 收口（error 档）——postmortem
+ * （provider-model-list）实证 agent 到 verify 末步才发现缺证据。本函数供 execute --done 的
+ * gates 调用（warn 级提示，不阻断 execute；verify 的 error 档语义不动）：UI 触达且证据
+ * 缺失时返回提示串，否则 null（非 UI / 证据在场 / gate off 零打扰）。
+ * @param {{ changeDir: string, specBase?: string }} opts
+ * @returns {string|null}
+ */
+export function uiEvidenceExecuteAdvisory({ changeDir, specBase = null }) {
+  try {
+    const gate = readUiVisualGate(specBase || join(changeDir, '..', '..', '..'))
+    const probe = runUiVisualProbe({ changeDir, gate })
+    if (!probe.applicable) return null
+    if (probe.evidencePresent) return null
+    const hard = gate === 'error'
+    return `UI 触达变更但变更目录尚无 ${UI_EVIDENCE_FILENAME}——渲染对照证据应在执行期随手落盘（截图/对照结论，收口只验在场不产新证据）${hard ? '；本仓 ui_visual_gate=error，verify 收口会硬拦' : '；verify 收口会警告'}。落盘路径：${join(changeDir, UI_EVIDENCE_FILENAME)}`
+  } catch {
+    return null // fail-soft：探测异常零打扰（verify 侧同款口径兜底）
+  }
+}
+
 /** design 文件变更清单行的路径粗提（反引号/裸路径行——探针侧仅作 UI 扩展名兜底命中，不追求全解）。 */
 function extractQuotedPaths(designText) {
   if (!designText) return []