sillyspec 3.33.2 → 3.33.3

package/AGENTS.md

@@ -33,7 +33,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
 3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档（轻量道即：FR 绑定+design 四节+用户批准先于动码，读代码探究不算动码）。测试按层适用：纯逻辑先写测试，行为契约断言用户可见行为，视觉样式与纯配置/文档不写测试（记「不适用：理由」，验收靠规范与人工）。
-4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）+ lint 即收口证据——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
 5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
 6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
 7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。

package/package.json

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

package/src/design-facts.js

@@ -387,7 +387,7 @@ export function generateDesignSkeleton({ changeName, decisionsText, author, now
   lines.push('- [ ] frontmatter 字段齐全（author/created_at/scale）')
   lines.push('- [ ] 引用所有当前版本 D-xxx@vN')
   lines.push('- [ ] 涉及生命周期关键词时含「生命周期契约表」或紧邻豁免短语')
-  lines.push('- [ ] UI 原型分级核对（涉前端文件时变更目录应有 prototype-*.html——新生成（定稿＝与实现同方言的真码产物，手绘仅限粗选，输出须带素材来源声明：token 源/组件来源/入口位置）或登记复用（复用须按 prototype-<名称>.html 命名，execute 才注入）或跳过原因记入风险登记；本仓形态未在 local.yaml ui_prototype 登记的，收口前补登记）')
+  lines.push('- [ ] UI 原型分级核对（涉前端文件时变更目录应有 prototype-*.html——新生成（定稿＝与实现同方言的真码产物，手绘仅限粗选，输出须带素材来源声明：token 源/组件来源/入口位置；产物必须可溯源到源码（管线编译/真实渲染捕获/登记复用三通道），手写 HTML 不得交付，对比稿供用户决策即定稿）或登记复用（复用须按 prototype-<名称>.html 命名，execute 才注入）或跳过原因记入风险登记；本仓形态未在 local.yaml ui_prototype 登记的，收口前补登记）')
   lines.push('- [ ] 不确定的问题标注「⚠️ 自审存疑」')
   lines.push('')
 

package/src/flow-review-pack.js

@@ -11,7 +11,7 @@
  *   ③ 摘要从冻结件本身算——change.patch 文本直解，不走活 git（review-material-pack 的
  *      extractDiffSummary 走活 git 解 base 那条路不能搬：防「包说的」与评审员手里冻结面漂移）。
  */
-import { readFileSync } from 'node:fs'
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 
 /** 材料包整体体积帽（对齐 review-material-pack.js PACK_MAX_CHARS 先例——包不能成为新的全量面）。 */
@@ -140,16 +140,47 @@ export function buildFreezeAttribution({ declaredFiles, freezeFiles, foreign })
   }
 }
 
+/**
+ * ledger 测试回执扫描（2026-10-21-review-rerun-scope）：verify-runs 各 runId 目录的
+ * test-result.json 按 change 匹配取目录名时间序最新一条（CLI 收口亲测产物，符合护栏③
+ * 机械抽取——非 agent 自述）。fail-soft：目录缺席/坏 JSON/无匹配 → null（调用方零注入）。
+ */
+export function findLatestTestReceipt(verifyRunsDir, changeName) {
+  try {
+    if (!verifyRunsDir || !changeName || !existsSync(verifyRunsDir)) return null
+    const runIds = readdirSync(verifyRunsDir).filter((d) => /^\d{14,}$/.test(d)).sort()
+    for (let i = runIds.length - 1; i >= 0; i--) {
+      const p = join(verifyRunsDir, runIds[i], 'test-result.json')
+      try {
+        const j = JSON.parse(readFileSync(p, 'utf8'))
+        // kind:'lint' 独立回执（verify-postcheck 同名同目录落盘）不是测试面——跳过防「测试回执」标签错挂 lint 结果
+        if (j && j.change === changeName && j.kind !== 'lint' && (j.status || j.exit_code !== undefined)) return j
+      } catch { /* 坏 JSON 跳过更旧轮 */ }
+    }
+  } catch { /* 扫描失败零注入 */ }
+  return null
+}
+
+/** 回执行渲染（机械——ran_at/status/exit/耗时/命令面截断）。 */
+function testReceiptLines(r) {
+  const cmd = String(r.command || '').replace(/\s+/g, ' ').slice(0, 120)
+  const dur = Number.isFinite(r.duration_ms) ? `${Math.round(r.duration_ms / 1000)}s` : '?'
+  return [
+    `  ledger 测试回执（CLI 收口亲测，${r.ran_at || '时间未知'}）：${r.status || 'unknown'} exit=${r.exit_code ?? '?'} ${dur} ｜ 面：${cmd}${String(r.command || '').length > 120 ? '…' : ''}`,
+    `  （回执为 CLI 亲测——评审按复跑口径抽验变更面即可，勿整体重跑）`,
+  ]
+}
+
 /**
  * 装配材料包注入行（唯一组包入口）：FR 表、patch 摘要、归属切分三子源各自可得各自产出、
  * 全缺返回 null（调用方零注入）。体积帽行级截断（不切半行），截断注记置于基准面语义行之前——
  * 语义行恒为末行；标题+正文+注记+语义行总长恒 ≤ PACK_MAX_CHARS（截断预留注记预算）。
  * requirements.md 读失败（缺件）→ FR 子段零产出；attribution 缺席/非法 → 归属子段零产出
  * （fail-soft 不抛穿，其余子段不受影响）。
- * @param {{ changeDir: string, patchText: string|null, attribution?: object|null }} args
+ * @param {{ changeDir: string, patchText: string|null, attribution?: object|null, testReceipt?: object|null }} args
  * @returns {{ lines: string[], truncated: boolean } | null}
  */
-export function assembleReviewPack({ changeDir, patchText, attribution = null }) {
+export function assembleReviewPack({ changeDir, patchText, attribution = null, testReceipt = null }) {
   let frRows = []
   try {
     frRows = parseFrBindingRows(readFileSync(join(changeDir, 'requirements.md'), 'utf8'))
@@ -167,6 +198,7 @@ export function assembleReviewPack({ changeDir, patchText, attribution = null })
   }
   const attr = normalizeAttribution(attribution)
   if (attr) body.push(...attributionLines(attr))
+  if (testReceipt && typeof testReceipt === 'object') body.push(...testReceiptLines(testReceipt))
   const note = `  …（材料包超 ${PACK_MAX_CHARS} 字符截断——需全文时定向查证并列明）`
   let budget = PACK_MAX_CHARS - PACK_TITLE.length - PACK_BASELINE.length - note.length
   const lines = [PACK_TITLE]

package/src/flow-review.js

@@ -313,6 +313,12 @@ export function renderReviewerTaskbook({ change, changeDir, head = null, probeLi
       `  （逐条作答：pass 给证据锚点 / gap 给缺件 / fail 给违诺实证——与上方检查单同口径，未答=未审）`,
     ] : []),
     ``,
+    `【复跑口径（与 AGENTS 自验口径同源——2026-10-21-review-rerun-scope）】`,
+    `  - 评审实测按「变更测试面」复跑：新测试 + 直接受影响既有文件；多文件合并一次 node --test 跑（逐文件跑每次付 ~10s 启动税）。`,
+    `  - 全量套件禁止：ledger 收口实测已跑变更面、CI test job 与 pre-push 门（lint+docs gate）已覆其余面——评审内重复跑全量是三重保险费（2026-10-20 会话画像实证：单次评审内两轮全量 8.4min）。`,
+    `  - 材料包含 ledger 测试回执时以回执为基线抽验复核，勿整体重跑。`,
+    `  - 长输出落 \`.sillyspec/.runtime/logs/\` 日志回看尾部（tail -50），勿整段读入上下文。`,
+    ``,
     `【纪律】只读——禁止修改任何文件、禁止 git 操作；唯一产物是 review.json。`,
     // 代行惯例（坑 flow-done-sentinel-token-split ②，2026-10-08 实证）：宿主无已注册子代理
     // 通道时无法照做「起子代理」——主会话按检查单代行自审可接受，reviewer 字段如实标注
@@ -341,8 +347,18 @@ export function renderReviewerTaskbook({ change, changeDir, head = null, probeLi
   return taskbook
 }
 
-/** 锚 sha 形态（7-40 位 hex）。 */
-const isAnchorSha = (v) => typeof v === 'string' && /^[0-9a-f]{7,40}$/i.test(v.trim())
+/**
+ * 锚 sha 词元提取（2026-10-20-closeout-roundtrip-slim）：字段含 7-40 位独立 hex 词元即通过，
+ * 返回归一化纯 sha（小写）；无词元返回 null。评审代理常在 sha 后附实测注记（今晚两例被整串
+ * 校验拒收，各多一轮收口往返）——词元提取容忍注记形态。归一化只发生在内存对象/返回值，
+ * 不回写文件（校验器只读铁律）。误命中面（如连写分支名含 ≥7 位 hex 段）后果有限：
+ * reviewedAgainst 是溯源锚非门禁比对；风险评估见变更 design 风险1。
+ */
+const extractAnchorSha = (v) => {
+  if (typeof v !== 'string') return null
+  const m = v.match(/(?<![0-9a-fA-F])[0-9a-fA-F]{7,40}(?![0-9a-fA-F])/)
+  return m ? m[0].toLowerCase() : null
+}
 
 /**
  * 变更的跨仓冻结面仓键（无 change-patch.json / 无 repos / 不可读 → null=单仓形态）。
@@ -376,16 +392,22 @@ export function validateReviewJson(path) {
   if (!['PASS', 'FAIL'].includes(r.verdict)) errors.push('verdict 必须为 PASS|FAIL')
   if (r.reviewedAgainst !== undefined) {
     if (typeof r.reviewedAgainst === 'string') {
-      if (!isAnchorSha(r.reviewedAgainst)) errors.push('reviewedAgainst 须为 7-40 位 hex sha（git rev-parse HEAD 输出，照抄任务书标注）')
+      const _anchor = extractAnchorSha(r.reviewedAgainst)
+      if (!_anchor) errors.push('reviewedAgainst 须为 7-40 位 hex sha（git rev-parse HEAD 输出，照抄任务书标注）')
+      else r.reviewedAgainst = _anchor
     } else if (r.reviewedAgainst && typeof r.reviewedAgainst === 'object' && !Array.isArray(r.reviewedAgainst)) {
-      if (!isAnchorSha(r.reviewedAgainst.workspace)) errors.push('reviewedAgainst 对象形态须含 workspace: 7-40 位 hex sha（主仓评审对象锚）')
+      const _ws = extractAnchorSha(r.reviewedAgainst.workspace)
+      if (!_ws) errors.push('reviewedAgainst 对象形态须含 workspace: 7-40 位 hex sha（主仓评审对象锚）')
+      else r.reviewedAgainst.workspace = _ws
       if (r.reviewedAgainst.repos !== undefined) {
         const repos = r.reviewedAgainst.repos
         if (!repos || typeof repos !== 'object' || Array.isArray(repos)) {
           errors.push('reviewedAgainst.repos 须为对象（仓键 → sha；仓键取 local.yaml repos 注册表键）')
         } else {
           for (const [k, v] of Object.entries(repos)) {
-            if (!isAnchorSha(v)) errors.push(`reviewedAgainst.repos.${k} 须为 7-40 位 hex sha（该仓 git rev-parse HEAD）`)
+            const _repo = extractAnchorSha(v)
+            if (!_repo) errors.push(`reviewedAgainst.repos.${k} 须为 7-40 位 hex sha（该仓 git rev-parse HEAD）`)
+            else repos[k] = _repo
           }
         }
       }
@@ -425,9 +447,10 @@ export function reviewAnchoredToHead(reviewPath, head) {
   try {
     const r = JSON.parse(readFileSync(reviewPath, 'utf8'))
     const raRaw = r?.reviewedAgainst
-    const ra = typeof raRaw === 'string' ? raRaw.trim().toLowerCase()
-      : (raRaw && typeof raRaw === 'object' && typeof raRaw.workspace === 'string' ? raRaw.workspace.trim().toLowerCase() : '')
-    if (!/^[0-9a-f]{7,40}$/.test(ra)) return false
+    const raRawNorm = typeof raRaw === 'string' ? raRaw
+      : (raRaw && typeof raRaw === 'object' && typeof raRaw.workspace === 'string' ? raRaw.workspace : '')
+    const ra = extractAnchorSha(raRawNorm)
+    if (!ra) return false
     return h === ra || h.startsWith(ra) || ra.startsWith(h)
   } catch { return false }
 }

package/src/flow.js

@@ -1921,6 +1921,7 @@ export async function cmdFlowDone({ change, cwd, specBase, runtimeRootOpt = null
             console.error(`   ① git commit 这些文件（信息尾缀带 (${change}) 或 （${change}），重跑本命令——冻结面自动并入`)
             console.error(`   ② 全部归属本变更：flow done --change ${change} --freeze-dirty`)
             console.error(`   ③ 接受审计缺口：flow done --change ${change} --accept-dirty-gap`)
+            console.error(`   💡 快速通道：脏文件全属并行会话在途/运行残渣且不在本变更交付面时，直接重跑带 --accept-dirty-gap（显式 pathspec 提交面已隔离归属；属本变更的文件必须走①提交）`)
             reportMidFail('patch')
             process.exit(1)
           }
@@ -2395,8 +2396,11 @@ export async function cmdFlowDone({ change, cwd, specBase, runtimeRootOpt = null
       } catch { /* 归属面 fail-soft：装配失败零注入该子段 */ }
       let _packLines = null
       try {
-        const { assembleReviewPack } = await import('./flow-review-pack.js')
-        const _pack = assembleReviewPack({ changeDir, patchText, attribution: _attribution })
+        const { assembleReviewPack, findLatestTestReceipt } = await import('./flow-review-pack.js')
+        // ledger 测试回执（2026-10-21-review-rerun-scope）：ledger 先于 review（SUBSTEPS 序），
+        // verify-runs 最新本变更 test-result 作回执注入——评审从「自己重跑」变「回执基线抽验」。
+        const _receipt = findLatestTestReceipt(join(specBase, '.runtime', 'verify-runs'), change)
+        const _pack = assembleReviewPack({ changeDir, patchText, attribution: _attribution, testReceipt: _receipt })
         if (_pack && Array.isArray(_pack.lines) && _pack.lines.length > 0) _packLines = _pack.lines
       } catch { /* 材料包面 fail-soft：装配失败零注入 */ }
       console.log(renderReviewerTaskbook({ change, changeDir, head: taskbookHead, probeLines: _probeLines, packLines: _packLines }))

package/src/run/gates.js

@@ -225,7 +225,7 @@ export function warnMissingUiPrototype(stageName, changeName, currentStepName, s
   const design = readFileSync(designPath, 'utf8')
   const feExts = [...new Set((design.match(/\.(vue|svelte|astro|tsx|jsx|css|scss|sass|less|styl|html)\b/gi) || []).map(s => s.replace('.', '').toLowerCase()))]
   if (feExts.length === 0) return
-  console.warn(`   ⚠️ design.md 命中前端文件类型（${feExts.join('/')}）但变更目录无 prototype-*.html——轻微样式改动可忽略；布局/交互流程级变化应补原型（sillyspec run brainstorm --reopen 回到「分段展示设计」，或直接让 agent 补生成；已有可复跑 HTML 原型则登记复用：复制进变更目录并命名 prototype-<名称>.html，execute 按此命名注入；本仓形态未在 local.yaml ui_prototype 登记的，收口前补登记——form: real-code 或 single-html+豁免 ruling）`)
+  console.warn(`   ⚠️ design.md 命中前端文件类型（${feExts.join('/')}）但变更目录无 prototype-*.html——轻微样式改动可忽略；布局/交互流程级变化应补原型（sillyspec run brainstorm --reopen 回到「分段展示设计」，或直接让 agent 补生成；已有可复跑 HTML 原型则登记复用：复制进变更目录并命名 prototype-<名称>.html，execute 按此命名注入；产物须可溯源到源码（管线编译/真实渲染捕获/登记复用），手写 HTML 不得交付，对比稿供用户决策即定稿；本仓形态未在 local.yaml ui_prototype 登记的，收口前补登记——form: real-code 或 single-html+豁免 ruling）`)
 }
 
 /**

package/src/stages/brainstorm.js

@@ -308,6 +308,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 - **可复跑**：能被本项目工具链跑起来（dev server / 组件文档页 / 构建产物均可，入口 HTML 从本地 node_modules 引真实库也行）——先查 scan 文档与现有前端代码就近发现项目原型管线，已有则复用；**历史原型先例同为单文件不构成管线存在**（51 个手绘先例是惯例债不是证据）；查无真码管线时**先单开一个轻量变更搭最小入口**（bootstrap 与业务变更分离），本变更按登记形态或降级声明执行
 - **高保真＝组件即实现原料，不是「看起来像」**：布局/组件/交互按真实效果呈现，execute 阶段直接对照搬组件，不经过"看图重新翻译"；**生成档输出必带素材来源声明**（真值 token 源文件路径 / 组件来源 / 入口位置——缺声明＝无源可查，2026-10-15 server-logs-panel 实证零声明）
 - **手绘单文件（自造样式）仅限一次性粗选对比，不得作为定稿原型**（frontend-apple-style 实证：手绘定稿后每条意见都要反向翻译回真实代码）；粗选定了方向，升级真码再收口
+- **产物必须可溯源到源码（三通道，手写 HTML 无合法出口）**：变更目录的 prototype-*.html 必须是——①本仓原型管线的编译产物，或 ②项目真实运行面的渲染捕获产物（dev server / 预览路由渲染真实组件后离线化导出；捕获脚本可随变更交付，捕获物仍是渲染结果，禁手改），或 ③登记复用的既有真码原型。**对比稿/视觉稿同样适用：凡供用户评审决策的原型即定稿提案，无粗选豁免**（2026-10-20 dsh 会话实证：视觉对比稿手写 HTML 交付，现状凭主题默认值想象）——粗选仅限口头或一次性草稿快速比选，不落变更目录充当交付物。重做/视觉类变更的现状基线必须真实渲染捕获或用户提供的现有截图，**禁止凭主题默认值想象现状、禁止手写复刻现状**
 - **例外与降级**：项目本身即单文件 HTML 方言（纯静态站）时单文件即真码，不适用手绘限定；无法同方言真码化（如目标平台无 HTML 运行面）时显式声明降级与理由请用户裁决留痕——静默降级会被收口「UI 视觉证据」探针拦下
 
 ### 铁律 — 必须等待用户确认设计

package/src/ui-visual.js

@@ -161,6 +161,9 @@ export function buildUiGuidanceLines(specBase = null, paths = []) {
     `🎨 UI 变更执行须知（本变更触及前端页面或 UI——advisory 引导非门禁）：`,
     `   1. 定稿原型必须是可复跑的真码产物（与实现同方言、能被本项目工具链构建）——手绘单文件`,
     `      仅限一次性粗选对比，不作为交付原型（2026-09-28 frontend-apple-style 实证：手绘定稿后每条意见都要反向翻译回真实代码）；`,
+    `      产物必须可溯源到源码（本仓管线编译 / 项目真实运行面渲染捕获 / 登记复用，三通道）——手写 HTML`,
+    `      无合法出口；对比稿/视觉稿供用户决策即定稿，无粗选豁免；重做类现状基线须真实捕获或用户截图，`,
+    `      禁止凭主题默认值想象现状（2026-10-20 dsh 会话实证）`,
     `   2. 开工先就近发现本项目原型管线：查本次变更触达项目自己的脚本、任务与工具链（多项目仓`,
     `      按触达路径就近，不假设全仓共享一套）；已有则复用，没有则现场搭最小管线并把入口留在`,
     `      项目惯例位置——下一个会话能自己发现；`,

package/templates/agents-instruction.md

@@ -32,7 +32,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
 3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档（轻量道即：FR 绑定+design 四节+用户批准先于动码，读代码探究不算动码）。测试按层适用：纯逻辑先写测试，行为契约断言用户可见行为，视觉样式与纯配置/文档不写测试（记「不适用：理由」，验收靠规范与人工）。
-4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）+ lint 即收口证据——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
 5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
 6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
 7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。