sillyspec 3.34.0 → 3.34.2

package/src/progress.js

@@ -155,6 +155,36 @@ export function resolveSessionIdentity({ flagSession = null, quickChangeName = n
  *
  *   无 pointer = 纯本地项目（从未平台 scan），正常走本地解析，不受影响。
  */
+/** 向上找 .git 所在目录（无 git 返回 null）——跨仓错绑告警的比对原语。 */
+function gitRootOf(startPath) {
+  let cur = resolve(startPath)
+  for (;;) {
+    if (existsSync(join(cur, '.git'))) return cur
+    const parent = dirname(cur)
+    if (parent === cur) return null
+    cur = parent
+  }
+}
+
+/** 跨仓错绑告警（2026-11-04-junction-guard-rename-content FR-01）：cwd 与解析出的
+ *  specRoot 分属不同 git 仓 = workspace junction/指针错绑形态（2026-11-04 跨工作区污染
+ *  事故实证：平台 workspace junction 指向 sillyspec 仓，CLI 忠实跟随零提示，sillyspec
+ *  内容经平台 token 推进平台 workspace）。双侧都有 .git 才比对（裸快照目录不误报）；
+ *  只告警不阻断（错绑下临时跨仓只读操作仍可用，由人裁决）。 */
+function warnIfCrossRepoSpecRoot(cwd, specRoot, pointerPath) {
+  let cwdRoot = null
+  let specRootGit = null
+  try { cwdRoot = gitRootOf(cwd) } catch { /* 比对失败静默（告警 fail-open） */ }
+  try { specRootGit = gitRootOf(specRoot) } catch { /* 同上 */ }
+  if (!cwdRoot || !specRootGit || cwdRoot === specRootGit) return
+  console.warn(
+    `⚠️ 平台 spec 根与当前目录分属不同 git 仓——workspace junction/指针疑似错绑（跨工作区污染事故形态）。\n` +
+    `   cwd 仓：${cwdRoot}\n` +
+    `   specRoot 仓：${specRootGit}\n` +
+    `   检查 ${pointerPath} 的 specRoot 与 ~/.sillyhub/daemon/specs/ 下对应 workspace 的 junction 绑定；或 sillyspec platform pointer --cleanup 后重扫。命令继续执行，请人工裁决。`
+  )
+}
+
 export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
   if (explicitSpecDir) return resolve(explicitSpecDir);
   const pointerPath = join(resolve(cwd), '.sillyspec-platform.json');
@@ -225,11 +255,13 @@ export function resolvePlatformSpecDir(cwd, explicitSpecDir = null) {
   // 偶发锚到 daemon junction 副本」）：daemon 写入的 pointer specRoot 可能是通向真实 spec 根的
   // junction/symlink 路径——经 junction 读写与真实路径同文件（无害）但路径呈现与比对漂移、
   // junction 随 daemon 生命周期可能蒸发。realpath 坍缩为真实路径（失败回退原值，保守不干预）。
+  let resolvedSpecRoot = ptr.specRoot
   try {
     const canonical = realpathSync(ptr.specRoot)
-    if (canonical && canonical !== ptr.specRoot) return canonical
+    if (canonical && canonical !== ptr.specRoot) resolvedSpecRoot = canonical
   } catch { /* realpath 失败（权限/竞态删除）→ 原值（上方已过存在性检查） */ }
-  return ptr.specRoot;
+  warnIfCrossRepoSpecRoot(cwd, resolvedSpecRoot, pointerPath)
+  return resolvedSpecRoot;
 }
 
 /**

package/src/route-hindsight.js

@@ -15,8 +15,10 @@
  *   - 标记文件 route-hindsight.json：per-repo 单条，每次标记整文件覆盖——提示语义即
  *     「上个轻量变更」。
  *
- * 指标四元组（口径）：
- *   designRewriteRatio / tasksRewriteRatio：终稿 vs 首版快照的行级改写比——复用
+ * 指标口径（判定三元组 + 观测一路）：
+ *   designRewriteRatio（判定 >0.5）/ tasksRewriteRatio（仅观测，判定已退役
+ *     2026-11-08-hindsight-tasks-ratio-retire——种子=v3 成功标准转写，横幅明文要求改写，
+ *     正常与不清不可分离）：终稿 vs 首版快照的行级改写比——复用
  *     flow-draft.computeEditRatio 同款 LCS 口径（改写行/首版行数，纯增行不计入；CRLF/LF
  *     归一后比对）。diff 面先做结构归一：剔 frontmatter 块、HTML 注释标记行（<!--）、空行
  *     ——惰性脚手架行（机器稿里约占半数）会把真实换血稀释到阈值以下（实测整写机器段仅得
@@ -39,11 +41,15 @@ import { writeAtomicSync } from './fs-atomic.js'
 import { computeEditRatio } from './flow-draft.js'
 import { runtimeStatePath } from './runtime-paths.js'
 
-/** 超阈判定常量（可调；口径：比例两路为严格大于——恰等于阈值不算超，保守防误标 R-01；
- * 计数两路为大于等于——2 维/2 次即系统性信号）。 */
+/** 超阈判定常量（可调；口径：比例路为严格大于——恰等于阈值不算超，保守防误标 R-01；
+ * 计数两路为大于等于——2 维/2 次即系统性信号）。
+ * tasksRewriteRatio 判定退役（2026-11-08-hindsight-tasks-ratio-retire）：种子自
+ * 2026-10-07-thin-tasks-v3 起为成功标准逐条转写（验收句≠实现步骤，文体必然不同），
+ * 且 flow start 横幅明文要求「机器种子按真实实现路径改写、增删改随意」——正常改写与
+ * 需求不清的改写不可区分（0.875/0.8 两连误标实证），阈值无分离度。计算面保留为观测
+ * （computeHindsightMetrics 照算照返回），未来有证据可重定口径后再恢复判定。 */
 export const HINDSIGHT_THRESHOLDS = {
   designRewriteRatio: 0.5, // design 机器稿改写比 > 0.5（50% 首版行被改写）
-  tasksRewriteRatio: 0.6,  // tasks 机器预填稿改写率 > 0.6
   blindDims: 2,            // 评审盲维命中（dimensionNotes='finding'）≥ 2 维
   testFailures: 2,         // 收口实测失败记录 ≥ 2 次
 }
@@ -229,9 +235,8 @@ export function markHindsight({ cwd, specBase, change, metrics }) {
   if (num(m.designRewriteRatio) > HINDSIGHT_THRESHOLDS.designRewriteRatio) {
     reasons.push(`design 机器稿改写比 ${num(m.designRewriteRatio)} > ${HINDSIGHT_THRESHOLDS.designRewriteRatio}`)
   }
-  if (num(m.tasksRewriteRatio) > HINDSIGHT_THRESHOLDS.tasksRewriteRatio) {
-    reasons.push(`tasks 机器预填稿改写率 ${num(m.tasksRewriteRatio)} > ${HINDSIGHT_THRESHOLDS.tasksRewriteRatio}`)
-  }
+  // tasksRewriteRatio 判定退役（2026-11-08-hindsight-tasks-ratio-retire）——metrics 字段
+  // 仍随标记文件落盘（观测面，向后兼容读取），不再参与判定与 reasons。
   if (num(m.blindDims) >= HINDSIGHT_THRESHOLDS.blindDims) {
     reasons.push(`评审盲维命中 ${num(m.blindDims)} 维 ≥ ${HINDSIGHT_THRESHOLDS.blindDims}`)
   }

package/src/spec-sync.js

@@ -17,7 +17,7 @@
 
 import { createHash } from 'crypto';
 import { timedAsync } from './timing.js';
-import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync, unlinkSync, rmSync } from 'fs';
 import { join, relative, sep } from 'path';
 import { bindSyncNoiseRoot, syncConnectionWarn, isConnectionClassStatus, noteSyncSuccess } from './sync-noise.js';
 import { runtimeStatePath } from './runtime-paths.js';
@@ -45,6 +45,67 @@ function toPosix(p) {
   return p.replace(/\\/g, '/');
 }
 
+// 全量清单拉取超时（2026-11-04-sync-fail-silent-fix FR-02）：全量清单是唯一稳定大响应
+// （生产实测 2.7MB；~1Mbps 入口链路需 ~25s），10s 硬编码使首拉/对账轮/倒退对账在慢链路
+// 恒熔断——缓存漂移后无收敛通道（228 条知识漏推事故的叠加因之二）。对齐 bundle 端点
+// 大超时档（sync.js PULL_BUNDLE_TIMEOUT_MS 同思路：大响应体独立口径）；增量（带 since）
+// 小响应维持 10s 噪音闸门不变。
+const MANIFEST_FULL_TIMEOUT_MS = 120_000;
+
+// 推送分批（2026-11-04-sync-push-chunking）：大积压单批 POST 在单请求预算内必死——
+// 生产实证 multi-agent-platform 工作区 15 天积压 2436 ops/45.7MB（base64 后 ~60MB），
+// 上传+服务端 apply 双超（客户端 30s 掐线、服务器 16-34s 处理后 400/中断），37 连败
+// 零落地。切块顺序推送：每块独立提交，已落地块推进服务器清单，失败即停由下轮 diff
+// 断点续传（锚点刷新后已落地路径自动出 diff）。env 仅调优，缺省零回归（小批量一块直发）。
+const PUSH_TIMEOUT_DEFAULT_MS = 30_000;
+const CHUNK_OPS_DEFAULT = 128;
+const CHUNK_BYTES_DEFAULT = 2 * 1024 * 1024;
+
+function resolvePushTimeoutMs() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_PUSH_TIMEOUT_MS);
+  if (Number.isFinite(raw) && raw >= 1000) return Math.floor(raw);
+  return PUSH_TIMEOUT_DEFAULT_MS;
+}
+
+function resolveChunkOps() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_CHUNK_OPS);
+  if (Number.isInteger(raw) && raw >= 1) return raw;
+  return CHUNK_OPS_DEFAULT;
+}
+
+function resolveChunkBytes() {
+  const raw = Number(process.env.SILLYSPEC_SPEC_SYNC_CHUNK_BYTES);
+  if (Number.isFinite(raw) && raw >= 1024) return Math.floor(raw);
+  return CHUNK_BYTES_DEFAULT;
+}
+
+/**
+ * 按 op 数与 base64 字节数双约束切块（顺序保序；单 op 超任一上限独占一块——
+ * 4.7MB 级 change.patch 单文件不切不丢弃）。行宽为粗估（content + path×2 + 包裹），
+ * 只为分块比例，无需精确。
+ */
+export function chunkOpsForPush(ops, opts = {}) {
+  const maxOps = opts.maxOps ?? resolveChunkOps();
+  const maxBytes = opts.maxBytes ?? resolveChunkBytes();
+  if (!Array.isArray(ops) || ops.length === 0) return [];
+  if (maxOps < 1 || maxBytes < 1) return [ops.slice()];
+  const chunks = [];
+  let cur = [];
+  let curBytes = 0;
+  for (const op of ops) {
+    const size = (op.content ? op.content.length : 0) + op.path.length * 2 + 96;
+    if (cur.length > 0 && (cur.length >= maxOps || curBytes + size > maxBytes)) {
+      chunks.push(cur);
+      cur = [];
+      curBytes = 0;
+    }
+    cur.push(op);
+    curBytes += size;
+  }
+  if (cur.length > 0) chunks.push(cur);
+  return chunks;
+}
+
 function debugLog(msg) {
   if (process.env.SILLYSPEC_DEBUG_SYNC) console.warn(msg);
 }
@@ -61,7 +122,7 @@ export function describeSyncError(err) {
     return '平台响应慢，本轮同步被总预算熔断让路（best-effort，下一条命令自动重试）';
   }
   if (err && err.name === 'TimeoutError') {
-    return '单请求超时（清单 10s / 推送 30s 口径，best-effort，下次自动重试）';
+    return '单请求超时（清单增量 10s/全量 120s；推送默认 30s，SILLYSPEC_SPEC_SYNC_PUSH_TIMEOUT_MS 可调；分批尺寸 SILLYSPEC_SPEC_SYNC_CHUNK_*；best-effort，下次自动重试）';
   }
   return err && err.message ? err.message : String(err);
 }
@@ -262,11 +323,17 @@ export function computeSpecOps(serverManifest, localFiles) {
   const ops = [];
 
   for (const r of renames) {
+    const localEntry = localMap.get(r.newPath);
     ops.push({
       op: 'rename',
       path: r.oldPath,
       new_path: r.newPath,
       base_version: server[r.oldPath].version,
+      // 内容随行（2026-11-04-junction-guard-rename-content FR-02）：服务端源行缺失（跨工作区
+      // 错绑/对端已清行）时无内容 rename 必被 422「源文件缺失的重命名操作必须携带文件内容」
+      // 拒收整批（生产实证文件树同步 5 连败卡死）；带 content 后服务端可直接物化目标路径，
+      // 源行在则照常移动语义。编码与 add/update 同款 base64。
+      content: (localEntry?.buf ?? readFileSync(localEntry?.absPath ?? join('.', r.newPath))).toString('base64'),
     });
   }
 
@@ -297,6 +364,12 @@ export function computeSpecOps(serverManifest, localFiles) {
   for (const p of localMap.keys()) {
     if (renamedNew.has(p)) continue;
     if (!serverSet.has(p)) {
+      // 平台已审候选不复活（2026-11-07-sync-proposed-no-revive）：平台知识页 merge/reject
+      // 待审候选后服务器软删（manifest 行 exists=false，不置墓碑）——此处若照常 add 会走
+      // 平台复活分支把已审条目推回待审区（2026-11-07 平台侧核查实证）。窄化判定：仅
+      // knowledge/proposed/ 前缀 + 软删行在场（平台处置的唯一可信证据；manifest 无行 =
+      // 从未同步的新提议，照常 add）。本地残留清理由 cleanupPlatformDisposedProposed 负责。
+      if (p.startsWith('knowledge/proposed/') && server[p]?.exists === false) continue;
       const localEntry = localMap.get(p);
       const content = (localEntry.buf ?? readFileSync(localEntry.absPath ?? join('.', p))).toString('base64');
       ops.push({
@@ -313,6 +386,39 @@ export function computeSpecOps(serverManifest, localFiles) {
   return ops;
 }
 
+/**
+ * 平台已审候选的本地残留清理（2026-11-07-sync-proposed-no-revive FR-02）：
+ * 「本地 knowledge/proposed/ 文件 ∩ 服务器 manifest exists=false 行」= 平台侧已
+ * merge/reject 处置过的候选在本地留下的残件（computeSpecOps 已拦其 add 复活）——
+ * 此处删除本地文件并提示，防止残留永久滞留（每次 sync 重算，幂等；无残留零输出）。
+ * 删除安全性：服务器侧该路径已无活文件（软删行），删本地不产生两端不一致；误删窗口
+ * 仅「同 slug 复写新内容 + 平台恰已处置同路径」（发生率极低，见变更 design R-02）。
+ * @returns {string[]} 已清理的 spec 相对路径列表
+ */
+export function cleanupPlatformDisposedProposed(specRoot, serverManifest) {
+  const server = serverManifest || {};
+  const disposed = Object.keys(server).filter(
+    (p) => p.startsWith('knowledge/proposed/') && server[p]?.exists === false
+  );
+  if (disposed.length === 0) return [];
+  const removed = [];
+  for (const p of disposed) {
+    // spec 相对路径 → 本地绝对路径（walkSpecTree 同源根；路径来自服务器清单为 POSIX 形态）
+    const abs = join(specRoot, ...p.split('/'));
+    if (!existsSync(abs)) continue; // 本地不在场的处置行零动作零上报（只清真残件）
+    try {
+      rmSync(abs, { force: true });
+      removed.push(p);
+    } catch { /* 删除失败不阻断同步——下轮重算重试（幂等） */ }
+  }
+  if (removed.length > 0) {
+    console.log(
+      `[spec-sync] 已清理 ${removed.length} 个平台已审核（合并/拒绝）的本地待审候选残留（不再回推复活）: ${removed.slice(0, 5).join(', ')}${removed.length > 5 ? ' 等' : ''}`
+    );
+  }
+  return removed;
+}
+
 /**
  * 从 ops 提取本次涉及的变更目录名集合（change_dirs 标注，D-005@v1）。
  *
@@ -755,7 +861,8 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
   try {
     const res = await fetch(cacheUsable ? `${manifestUrl}?since=${manifestCache.spec_version}` : manifestUrl, {
       headers: { Authorization: `Bearer ${platform.token}` },
-      signal: withSignal(10000),
+      // 超时分档（FR-02）：增量（带 since）小响应 10s；全量大响应 120s（慢链路全量对账可达）
+      signal: withSignal(cacheUsable ? 10000 : MANIFEST_FULL_TIMEOUT_MS),
     });
     if (!res.ok) {
       // ql-20260818-008：debugLog → console.warn。树同步失败原本完全静默（要
@@ -787,7 +894,7 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
       debugLog(`[spec-sync] spec_version 倒退（${manifestCache.spec_version} → ${body.spec_version}，服务端重建？）——回退全量清单对账`);
       const full = await fetch(manifestUrl, {
         headers: { Authorization: `Bearer ${platform.token}` },
-        signal: withSignal(10000),
+        signal: withSignal(MANIFEST_FULL_TIMEOUT_MS), // 倒退对账=全量大响应（FR-02 同档）
       });
       if (!full.ok) {
         const failCount = bumpFailStreak(specRoot, logLabel, `倒退对账全量 HTTP ${full.status}`);
@@ -824,6 +931,11 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
   // 2. walk/hash/diff
   const entries = walkSpecTree(specRoot);
   const localFiles = hashFiles(entries);
+  // 平台已审候选残留清理（2026-11-07-sync-proposed-no-revive FR-02）：computeSpecOps 已拦
+  // 其 add 复活，此处删本地残件+提示（幂等；walk 已完成，删除不影响本轮 diff 结果）。
+  try {
+    cleanupPlatformDisposedProposed(specRoot, serverManifest);
+  } catch { /* 清理 fail-soft——不阻断文件树同步 */ }
   let ops = computeSpecOps(serverManifest, localFiles);
 
   // 旧副本回推防护（并行会话一致性）：上次同步后本地从未改动的文件不回推覆盖服务器新内容。
@@ -863,30 +975,47 @@ async function syncSpecTreeImpl(specRoot, platform, changeName, opts = {}) {
     return { synced: 0, ok: true };
   }
 
-  // 3. POST ops
+  // 3. POST ops（2026-11-04-sync-push-chunking：分批顺序推送——单批大积压在单请求
+  //    预算内上传+服务端 apply 双超零落地；切块后每块独立提交，失败即停下轮续传）
   try {
-    const res = await fetch(syncUrl, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${platform.token}`,
-      },
-      body: JSON.stringify({ ops }),
-      signal: withSignal(30000),
-    });
-    if (!res.ok) {
-      const raw = await res.text().catch(() => '');
-      const detail = describeErrorBody(res.status, raw);
-      const failCount = bumpFailStreak(specRoot, logLabel, detail);
-      const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
-      if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
-      else console.warn(line);
-      if (failCount >= FAIL_STREAK_ESCALATE_AT) {
-        console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+    const chunks = chunkOpsForPush(ops);
+    if (chunks.length > 1) {
+      console.log(`[spec-sync] 推送分批：${ops.length} ops 切 ${chunks.length} 块顺序提交（块上限 ${resolveChunkOps()} ops / ${Math.round(resolveChunkBytes() / 1024)}KB 估算）: ${logLabel}`);
+    }
+    let landedChunks = 0;
+    const body = { conflict: false, server_versions: {}, platform_deleted: [] };
+    for (let ci = 0; ci < chunks.length; ci++) {
+      const res = await fetch(syncUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${platform.token}`,
+        },
+        body: JSON.stringify({ ops: chunks[ci] }),
+        signal: withSignal(resolvePushTimeoutMs()),
+      });
+      if (!res.ok) {
+        const raw = await res.text().catch(() => '');
+        const detail = describeErrorBody(res.status, raw);
+        const failCount = bumpFailStreak(specRoot, logLabel, detail);
+        const landedNote = landedChunks > 0 ? `（前 ${landedChunks}/${chunks.length} 块已落地，下轮自动续传未落地部分）` : '';
+        const line = `[spec-sync] 同步请求失败 HTTP ${res.status}（文件树本次未同步，下次自动重试）${landedNote}: ${logLabel}${detail ? ` —— ${detail}` : ''}`;
+        if (isConnectionClassStatus(res.status)) syncConnectionWarn(line);
+        else console.warn(line);
+        if (failCount >= FAIL_STREAK_ESCALATE_AT) {
+          console.warn(`🚨 [spec-sync] 已连续 ${failCount} 次同步失败——平台文件树可能持续落后（变更中心或仍显示「进行中」/旧内容）: ${logLabel}`);
+        }
+        return { synced: 0, ok: false };
       }
-      return { synced: 0, ok: false };
+      const chunkBody = await res.json().catch(() => ({}));
+      landedChunks += 1;
+      // 块响应合并成单批等价形状：conflict 任一块命中即真；server_versions /
+      // platform_deleted 逐块累积（块间路径互斥——computeSpecOps 每 path 至多一 op）。
+      if (chunkBody.conflict) body.conflict = true;
+      Object.assign(body.server_versions, chunkBody.server_versions || {});
+      if (Array.isArray(chunkBody.platform_deleted)) body.platform_deleted.push(...chunkBody.platform_deleted);
+      if (chunks.length > 1) debugLog(`[spec-sync] 分批 ${ci + 1}/${chunks.length} 落地（${chunks[ci].length} ops）`);
     }
-    const body = await res.json().catch(() => ({}));
     if (body.conflict) {
       // HUB-08 冲突闭环：落 spec-sync-conflict-<change>.json（与进度 sync-conflict-* 同目录），
       // 供 platform status 列出 + platform resolve 三态处置。此前只 warn 返回，下次 sync 用
@@ -1023,5 +1152,6 @@ export default {
   filterStaleUpdates,
   dropFollowServerUpdates,
   partitionConflictPaths,
+  chunkOpsForPush,
   syncSpecTree,
 };

package/src/stages/brainstorm.js

@@ -111,7 +111,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 4. 探索顺序（按需）：目的 → 约束 → 边界 → 成功标准
 5. **先挖为什么**：不只问「要什么」，要问出「为什么现在做、不做会怎样」（动机是后续替你补全没提的那一百个决定的依据）；到本步出口仍说不清动机 → 不许进入「提出 2-3 种方案」，先把动机问出来
 6. **实现方式的选择权归谁**：技术栈/平台/语言/库/存储介质这类「怎么做」的选择，问清哪些是用户有强意见要谈的、哪些是交给你选的；你选的按决策记录规则落盘并把 answer 标注「我的判断」（不是用户同意过的）
-7. 多选题优于开放式问题；被问「你觉得呢/先猜一个」时给一个具体方案并标「我的判断」，不要空转追问
+7. 提问分型（意图问开放、决策给选项）：意图/动机类问题（用户想要什么、为什么、成功什么样）必须开放式提出，不附任何示例选项——用户自己的措辞携带选项装不下的意图，给选项会锚定用户；存在可命名取舍的决策类问题才给具名选项，每个选项附一句代价，必带推荐与理由，禁止裸问「选哪个」。被问「你觉得呢/先猜一个」时给一个具体方案并标「我的判断」，不要空转追问
 8. YAGNI — 砍掉不需要的功能
 
 ### B2. 分块回放（Playback——边理解边复述，与追问交替）

package/src/stages/execute.js

@@ -21,7 +21,7 @@ import { collectExecuteChangedFiles, computeDecisionTouches, renderDecisionTouch
 // （test 直 import 本文件皆此形态）触发 stages/index.js 顶层 stageRegistry 对本文件 definition
 // const 的 TDZ 求值（ESM 环实证 2026-09-14）。此处为同格式本地孪生，漂移由
 // test/knowledge-inject.test.mjs 格式等价断言锁定——改 prompt.js 版必同步改此处。
-import { matchKnowledge } from '../knowledge-match.js'
+import { matchKnowledge, resultChannel } from '../knowledge-match.js'
 import { matchKnowledgeWithScope, graphPathCandidates, scopeTelemetryRefs } from '../knowledge-graph.js'
 import { appendKnowledgeHit } from '../knowledge-hits.js'
 
@@ -136,10 +136,12 @@ function buildWaveKnowledgeSection(changeDir, wave) {
     }
     }
     try {
+      // channel 单源记录（FR-04，2026-11-05-knowledge-search-observability）——画像/调优数据地基
       appendKnowledgeHit(path.join(specBase, '.runtime'), {
         type: 'inject',
         change: path.basename(changeDir),
         query,
+        channel: resultChannel(result),
         matchedFiles: result.matched ? [...humanEntries, ...routeHits].map(e => (e.anchor ? `${e.file}#${e.anchor}` : e.file)) : [],
         ...(result.matched ? (() => {
           const scopeMatchedFiles = scopeTelemetryRefs(result, { includeRejected: false })

package/src/stages/explore.js

@@ -22,11 +22,13 @@ export const definition = {
    - 在途面（出方向建议前）→ \`sillyspec status\` 活跃变更一览——结论别跟在途工作撞车
 4. 输出 2-3 个有价值方向、关键风险和下一步建议
 5. 如果用户要求保存结论，先明确保存位置，再写入对应文档
-6. 讨论 UI/交互方案且用户明确要求原型时，按下方「HTML 原型生成」执行
+6. 讨论 UI/交互方案或状态机/流程/时序类歧义且用户明确要求原型时，按下方「HTML 原型生成」执行
 
 ### HTML 原型生成（仅用户明确要求时）
-探索保持只读姿态：不主动写原型文件；UI 讨论成形时可以提议（"要不要出个原型看效果"），用户同意后再生成。探索期原型是**粗选对比件**（求快不求真，手绘单文件含内联 CSS+JS 在探索期合法，浏览器直接打开）：
+探索保持只读姿态：不主动写原型文件；UI/交互讨论成形、或状态机/流程/时序类歧义文字多轮问答装不下时，可以提议（"要不要出个原型看效果"），用户同意后再生成。探索期原型是**粗选对比件**（求快不求真，手绘单文件含内联 CSS+JS 在探索期合法，浏览器直接打开）：
 - 呈现讨论中的布局/组件/交互流程——用户看到的是"这个方案做出来长什么样"，不是示意图；能用项目真实组件库/设计 token 观感的尽量用（先读 scan 文档与现有前端代码），降低与真实效果的偏差
+- 逻辑形（状态机/流转/时序类歧义用）：把流转规则写成内联纯逻辑模块，配状态面板（每步操作后重渲染全量状态）+ 领域语言标注，让用户亲手把玩边界场景代替文字推演；非 JS 项目即「JS 复刻的模拟器」——验证的是复刻件非真码，提议时声明可能的翻译失真；逻辑形不进变更目录（prototype-*.html 命名是 UI 契约件专属），结论以 design/decisions 文字落盘
+- 多方案对比时：各方案须在布局/信息层级（UI 形）或流转结构（逻辑形）上实质性分歧，颜色文案级差异不构成对比方案；mock 数据取真实形状与密度，不在空态页面上做判断
 - 保存到 \`{SPEC_ROOT}/explore/prototype-<名称>.html\`（目录不存在则先创建；用户指定了其他位置则从其指定）
 - 原型是探索讨论工具、不是交付物，也不是实现代码——不要顺手把原型接进项目源码或构建；话题后续进入 brainstorm 时分两路：已是可复跑真码的原型复制到 \`{SPEC_ROOT}/changes/<变更名>/\`（**保留 \`prototype-<名称>.html\` 命名**——execute 按此命名注入，改名＝不注入）走登记复用；手绘粗选件只是方向输入，brainstorm 定稿须按其「生成要求」升级为真码（同方言/可复跑），不得把手绘件直接当定稿登记