sillyspec 3.26.1 → 3.26.2

package/.sillyspec-platform.json

@@ -3,5 +3,5 @@
   "runtimeRoot": null,
   "workspaceId": null,
   "scanRunId": null,
-  "savedAt": "2026-08-11T04:01:27.160Z"
+  "savedAt": "2026-08-11T08:03:50.313Z"
 }

package/package.json

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

package/src/classify-change.js

@@ -5,6 +5,10 @@
  * 供 auto 模式决定内部流程深度。
  */
 
+import { existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import jsYaml from 'js-yaml'
+
 /**
  * 用户显式指定的关键词 → 强制模式
  */
@@ -24,12 +28,36 @@ const FORCE_QUICK_PATTERNS = [
   /修复.*\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 配置
+ * @param {object} [opts.localConfig] - local.yaml auto_mode 段（由 readAutoModeFromLocalYaml 读出）
  * @returns {{ mode: 'quick'|'auto'|'full', reason: string }}
  */
 export function classifyChange({ description = '', explicitMode, localConfig } = {}) {
@@ -44,13 +72,21 @@ export function classifyChange({ description = '', explicitMode, localConfig } =
     const forceQuickPatterns = localConfig.force_quick_patterns || []
 
     for (const pattern of forceFullPatterns) {
-      if (new RegExp(pattern, 'i').test(description)) {
-        return { mode: 'full', reason: `local.yaml force_full_pattern 匹配: ${pattern}` }
+      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) {
-      if (new RegExp(pattern, 'i').test(description)) {
-        return { mode: 'quick', reason: `local.yaml force_quick_pattern 匹配: ${pattern}` }
+      try {
+        if (new RegExp(pattern, 'i').test(description)) {
+          return { mode: 'quick', reason: `local.yaml force_quick_pattern 匹配: ${pattern}` }
+        }
+      } catch {
+        // 非法正则跳过
       }
     }
   }

package/src/config-schema.js

@@ -0,0 +1,287 @@
+/**
+ * config-schema.js — local.yaml 配置键的单一数据源。
+ *
+ * 定位：`.sillyspec/local.yaml` 是 gitignored 的机器+人混写配置，键散落在 ~10 个 reader
+ * 里（detect / verify-postcheck / sync / dispatch / worktree-guard / classify-change …），
+ * 外部项目的 agent 无从得知有哪些键、哪些生效。本模块把「全部已知键 + 生效状态 + 读取点」
+ * 集中成一张表，供：
+ *   - `sillyspec config schema`（人类可读树 / --json 机读）打印；
+ *   - `sillyspec init` 调 renderExample() 落盘脱敏 local.yaml.example 给人/外部 agent 看。
+ *
+ * 单一真相 = LOCAL_YAML_SCHEMA。renderExample() 是策展模板（YAML 形态各异：嵌套 / inline
+ * flow / 顶层标量，自动生成不如策展可读），由测试「每个 live 键路径必出现于 example 文本」
+ * 耦合保证不漂移——加键忘 example 则测试红。
+ *
+ * reader 引用一律用符号名（readMcpConfig / extractModules），**不用行号**——行号随重构漂移，
+ * 符号名稳定可 grep。
+ *
+ * status 语义：
+ * - live        真有 reader 从 local.yaml 读并起效（配了即生效）。
+ * - declared    代码/JSDoc/prompt 声明过，但无 reader 真读 local.yaml（或调用方未传），配了不生效。
+ *               诚实标出，避免 agent 白配 + 暴露待接线债。
+ */
+
+/**
+ * @typedef {Object} SchemaKey
+ * @property {string} path          点分路径（mcp.url / worktree-hook.readonlyCommands）
+ * @property {string} type          string|enum|integer|object|array|scalar
+ * @property {string[]} [values]    enum 取值
+ * @property {boolean} [required]   凭据类必填（两键齐全才视为有效源）
+ * @property {boolean} [secret]     敏感凭据，example 用占位符
+ * @property {boolean} [optional]   可选键
+ * @property {string} status        live|declared
+ * @property {string[]} readers     读取点符号名（稳定可 grep），declared 键留空数组
+ * @property {string} desc          一句话说明
+ * @property {string} example       脱敏示例值（secret 键用占位符）
+ *
+ * @typedef {Object} SchemaSection
+ * @property {string} id
+ * @property {string} title
+ * @property {string} note          段说明（写入来源 / 注意事项）
+ * @property {SchemaKey[]} keys
+ */
+
+/** @type {{ file: string, note: string, sections: SchemaSection[] }} */
+export const LOCAL_YAML_SCHEMA = {
+  file: '.sillyspec/local.yaml',
+  note: 'gitignored（含敏感凭据勿提交）；脱敏示例 local.yaml.example 由 sillyspec init 生成（可提交）。',
+  sections: [
+    {
+      id: 'project',
+      title: '项目类型',
+      note: '由 sillyspec local detect 纯 fs 嗅探写入，一般无需手填。',
+      keys: [
+        {
+          path: 'project.type',
+          type: 'enum',
+          values: ['nodejs', 'maven', 'gradle', 'make', 'generic'],
+          status: 'live',
+          readers: ['detectLocalYaml (src/local-detect.js)', 'extractProjectType (src/worktree-deps.js)'],
+          desc: '项目类型，决定默认 commands 嗅探与 worktree 依赖策略。',
+          example: 'nodejs',
+        },
+      ],
+    },
+    {
+      id: 'commands',
+      title: '构建/测试/lint 命令',
+      note: 'detect 核验 package.json(或对应构建文件) scripts 存在性后才写对应键；缺失则不写。agent 可改。',
+      keys: [
+        { path: 'commands.build', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '构建命令。', example: 'npm run build' },
+        { path: 'commands.test', type: 'string', optional: true, status: 'live', readers: ['extractTestCommand (src/verify-postcheck.js)', 'validateCommands (src/scan-postcheck.js)'], desc: '测试命令——verify 阶段 CLI 亲自执行此命令与 verify-result.md 对账，实测失败即阻断。', example: 'npm test' },
+        { path: 'commands.lint', type: 'string', optional: true, status: 'live', readers: ['detectLocalYaml (src/local-detect.js)', 'validateCommands (src/scan-postcheck.js)'], desc: 'lint 命令。', example: 'npm run lint' },
+        { path: 'commands.install', type: 'string', optional: true, status: 'live', readers: ['extractInstallCommand (src/worktree-deps.js)'], desc: '依赖安装命令（worktree 依赖 provisioning 用）。', example: 'npm install' },
+      ],
+    },
+    {
+      id: 'mcp',
+      title: 'SillyHub MCP 客户端凭据（派发用）',
+      note: 'agent 手填，或 sillyspec platform connect 在 mcp 段缺失时同源自动填（§7.4）。两键齐全才生效，否则回退 env SILLYHUB_MCP_URL/TOKEN。',
+      keys: [
+        { path: 'mcp.url', type: 'string', required: true, secret: true, status: 'live', readers: ['readMcpConfig (src/sillyhub-mcp/config.js)'], desc: 'SillyHub MCP 服务地址（尾斜杠自动归一）。', example: 'https://your-sillyhub.example.com' },
+        { path: 'mcp.token', type: 'string', required: true, secret: true, status: 'live', readers: ['readMcpConfig (src/sillyhub-mcp/config.js)'], desc: 'SillyHub MCP 认证 token。', example: '<your-mcp-token>' },
+      ],
+    },
+    {
+      id: 'platform',
+      title: 'SillyHub 平台同步',
+      note: 'sillyspec platform connect 写入（含 ping 验活）；手填亦可。user/last_connected 可空或自动写。',
+      keys: [
+        { path: 'platform.url', type: 'string', required: true, secret: true, status: 'live', readers: ['SyncManager._getPlatform (src/sync.js)'], desc: 'SillyHub 平台地址。', example: 'https://your-sillyhub.example.com' },
+        { path: 'platform.token', type: 'string', required: true, secret: true, status: 'live', readers: ['SyncManager._getPlatform (src/sync.js)'], desc: '平台认证 token（Bearer）。', example: '<your-platform-token>' },
+        { path: 'platform.user', type: 'string', optional: true, status: 'live', readers: ['resolvePlatformUser / SyncManager.connect (src/sync.js)'], desc: '推送者身份；缺则回退 git user.name / env。推送时进 X-SillySpec-User header。', example: 'alice' },
+        { path: 'platform.last_connected', type: 'string', optional: true, status: 'live', readers: ['SyncManager.connect (src/sync.js)'], desc: 'connect 成功时间戳（ISO），自动写，勿手填。', example: '2026-08-11T00:00:00.000Z' },
+      ],
+    },
+    {
+      id: 'dispatch',
+      title: '派发调参',
+      note: '仅在确知调优值时填，否则留默认。',
+      keys: [
+        { path: 'dispatch.probe_ttl_ms', type: 'integer', optional: true, status: 'live', readers: ['readProbeTtlFromLocalYaml (src/dispatch/probe.js)'], desc: '派发探测负面缓存 TTL（毫秒，默认 60000）。daemon 抖动期避免反复探测。', example: '60000' },
+        { path: 'dispatch.poll_interval_ms', type: 'integer', optional: true, status: 'declared', readers: [], desc: '【路径A 预留·未落地】renderSillyHubInstruction 注入的轮询文本提及，但 isPathASupported()=false 该指令当前不注入；路径A 落地后接线，配了暂不生效。', example: '15000' },
+        { path: 'dispatch.worker_timeout_ms', type: 'integer', optional: true, status: 'declared', readers: [], desc: '【路径A 预留·未落地】同 poll_interval_ms，路径A 落地后接线，配了暂不生效。', example: '60000' },
+      ],
+    },
+    {
+      id: 'modules',
+      title: 'monorepo 子模块映射',
+      note: 'test_strategy: module 时，按 git diff 命中的模块子集收窄测试。只支持 inline flow 形态（extractModules 不解析嵌套展开式）。',
+      keys: [
+        { path: 'modules.<name>.path', type: 'string', optional: true, status: 'live', readers: ['extractModules (src/verify-postcheck.js)', 'parseLocalYamlModules (src/plan-postcheck.js)', 'extractModulePaths (src/worktree-deps.js)'], desc: '子模块目录路径（相对仓库根）。', example: 'frontend/' },
+        { path: 'modules.<name>.test', type: 'string', optional: true, status: 'live', readers: ['extractModules (src/verify-postcheck.js)'], desc: '该子模块的测试命令。', example: 'cd frontend && pnpm test' },
+      ],
+    },
+    {
+      id: 'test_strategy',
+      title: '测试策略',
+      note: 'verify 阶段 CLI 对账的收窄策略。',
+      keys: [
+        { path: 'test_strategy', type: 'enum', values: ['full', 'module'], optional: true, status: 'live', readers: ['extractTestStrategy (src/verify-postcheck.js)'], desc: 'full=全量 commands.test；module=按 git diff 命中 modules 子集收窄（需配 modules）。缺省=全量。', example: 'full' },
+      ],
+    },
+    {
+      id: 'known_failures',
+      title: '预存失败豁免清单',
+      note: '变更前就失败的测试行，豁免后不计入 verify 阻断。支持块列表或 inline 数组。务必定期复核，避免误豁免本变更引入的真实失败。',
+      keys: [
+        { path: 'known_failures', type: 'array', optional: true, status: 'live', readers: ['extractKnownFailures (src/verify-postcheck.js)'], desc: '失败行模式列表（匹配测试输出失败行）。', example: 'tests/some-old-test' },
+      ],
+    },
+    {
+      id: 'worktree-hook',
+      title: 'worktree-guard 扩展',
+      note: 'execute worktree 隔离期内放行的额外只读命令。键名用 camelCase（parseSimpleYaml 原样保留）。',
+      keys: [
+        { path: 'worktree-hook.readonlyCommands', type: 'array', optional: true, status: 'live', readers: ['loadLocalConfig (src/hooks/worktree-guard.js)'], desc: '额外放行的只读命令名列表（如 rg/fd），绕过 worktree-guard 写操作拦截。', example: 'rg' },
+      ],
+    },
+    {
+      id: 'auto_mode',
+      title: '变更规模自动分类',
+      note: 'sillyspec run auto 时，readAutoModeFromLocalYaml 读本段传 classifyChange 的 localConfig，force_*_patterns 匹配需求描述则强制对应模式。',
+      keys: [
+        { path: 'auto_mode.force_full_patterns', type: 'array', optional: true, status: 'live', readers: ['readAutoModeFromLocalYaml + classifyChange (src/classify-change.js)', 'runCommand (src/run/command.js)'], desc: '需求描述匹配任一正则（i 大小写无关）→ 强制 full 流程。非法正则跳过不崩。', example: '数据库|migration' },
+        { path: 'auto_mode.force_quick_patterns', type: 'array', optional: true, status: 'live', readers: ['readAutoModeFromLocalYaml + classifyChange (src/classify-change.js)', 'runCommand (src/run/command.js)'], desc: '需求描述匹配任一正则 → 强制 quick。非法正则跳过不崩。', example: 'fix typo' },
+      ],
+    },
+  ],
+};
+
+/** 全部键（拍平），便于 JSON 输出与 example 耦合测试。 */
+export function flatKeys() {
+  return LOCAL_YAML_SCHEMA.sections.flatMap((s) => s.keys.map((k) => ({ section: s.id, ...k })));
+}
+
+/** 人类可读树形 schema 文本。live 在前、declared 在后，段内逐键列 path/type/约束/读取点/说明。 */
+export function renderSchemaHuman() {
+  const L = [];
+  L.push('SillySpec local.yaml 配置清单');
+  L.push(`文件：${LOCAL_YAML_SCHEMA.file} — ${LOCAL_YAML_SCHEMA.note}`);
+  L.push('数据源：src/config-schema.js（本表唯一真相；reader 见各键「读取点」，符号名可 grep）');
+  L.push('');
+
+  const all = flatKeys();
+  const live = all.filter((k) => k.status === 'live');
+  const declared = all.filter((k) => k.status === 'declared');
+
+  L.push(`━━━ 生效（${live.length} 键，配了即生效） ━━━`);
+  L.push('');
+  for (const s of LOCAL_YAML_SCHEMA.sections) {
+    const keys = s.keys.filter((k) => k.status === 'live');
+    if (keys.length === 0) continue;
+    L.push(`[${s.id}] ${s.title}`);
+    L.push(`    ${s.note}`);
+    for (const k of keys) {
+      L.push(`  ${k.path}${formatConstraint(k)}    ${k.desc}`);
+      if (k.readers.length) L.push(`      读取点：${k.readers.join('；')}`);
+    }
+    L.push('');
+  }
+
+  L.push(`━━━ 声明但未接线（${declared.length} 键，配了不生效 / 待接线债） ━━━`);
+  L.push('');
+  for (const s of LOCAL_YAML_SCHEMA.sections) {
+    const keys = s.keys.filter((k) => k.status === 'declared');
+    if (keys.length === 0) continue;
+    L.push(`[${s.id}] ${s.title}`);
+    L.push(`    ${s.note}`);
+    for (const k of keys) {
+      L.push(`  ${k.path}${formatConstraint(k)}    ${k.desc}`);
+    }
+    L.push('');
+  }
+  return L.join('\n');
+}
+
+function formatConstraint(k) {
+  const tags = [];
+  if (k.required) tags.push('必填');
+  if (k.optional) tags.push('可选');
+  if (k.secret) tags.push('凭据');
+  if (k.type === 'enum' && k.values) tags.push(k.values.join('|'));
+  else tags.push(k.type);
+  return tags.length ? `  [${tags.join(' · ')}]` : '';
+}
+
+/** 机读 JSON（程序化消费）。结构 = LOCAL_YAML_SCHEMA 本体 + flatKeys 视图。 */
+export function renderSchemaJson() {
+  return JSON.stringify({
+    file: LOCAL_YAML_SCHEMA.file,
+    note: LOCAL_YAML_SCHEMA.note,
+    sections: LOCAL_YAML_SCHEMA.sections,
+    keys: flatKeys().map(({ section, path, type, values, required, optional, secret, status, readers, desc }) => ({
+      section, path, type, values, required, optional, secret, status, readers, desc,
+    })),
+  }, null, 2);
+}
+
+/**
+ * 脱敏 local.yaml 示例文本（sillyspec init 落盘用）。
+ * 策展模板（非自动生成）：YAML 形态各异（嵌套/inline flow/顶层标量），策展可读性远胜自动拼。
+ * 与 SCHEMA 的耦合由测试保证：每个 live 键路径必出现于本文本。
+ */
+export function renderExample() {
+  return `# SillySpec local.yaml — 脱敏示例（由 sillyspec init 生成，可提交）
+# 真实配置文件 .sillyspec/local.yaml 是 gitignored（含敏感凭据）。
+# 用法：复制本文件为 .sillyspec/local.yaml，填真实值；或直接 sillyspec platform connect 自动写凭据段。
+# 全部键与生效状态：sillyspec config schema
+
+# ── 项目类型（sillyspec local detect 自动写入，一般无需手填）──
+project:
+  type: nodejs   # nodejs | maven | gradle | make | generic
+
+# ── 构建/测试/lint 命令（detect 核验 scripts 存在性后才写；缺失键省略）──
+commands:
+  build: npm run build
+  test: npm test
+  lint: npm run lint
+  # install: npm install   # worktree 依赖安装命令
+
+# ── SillyHub MCP 客户端凭据（派发到 worker 用）──
+# agent 手填，或 sillyspec platform connect 在 mcp 段缺失时同源自动填。
+# 两键齐全才生效；缺则回退环境变量 SILLYHUB_MCP_URL / SILLYHUB_MCP_TOKEN。
+mcp:
+  url: https://your-sillyhub.example.com
+  token: <your-mcp-token>
+
+# ── SillyHub 平台同步（sillyspec platform connect 写入，含 ping 验活）──
+platform:
+  url: https://your-sillyhub.example.com
+  token: <your-platform-token>
+  user: alice                 # 推送者身份（可空，回退 git user.name / env）
+  # last_connected: 2026-08-11T00:00:00.000Z   # connect 自动写，勿手填
+
+# ── 派发调参（仅确知调优值时填，否则留默认）──
+dispatch:
+  probe_ttl_ms: 60000         # 派发探测负面缓存 TTL（默认 60000）
+  # poll_interval_ms: 15000   # ⚠ 路径A 预留·未落地，配了暂不生效
+  # worker_timeout_ms: 60000  # ⚠ 路径A 预留·未落地，配了暂不生效
+
+# ── monorepo 子模块映射（test_strategy: module 时按 git diff 命中模块收窄测试）──
+# 只支持 inline flow 形态（嵌套展开式解析不出）：
+modules:
+  frontend: { path: "frontend/", test: "cd frontend && pnpm test" }
+  backend: { path: "backend/", test: "cd backend && npm test" }
+
+# ── 测试策略：full=全量 commands.test | module=按命中模块收窄（需配 modules）──
+test_strategy: full
+
+# ── 预存失败豁免清单（变更前就失败的测试行；务必定期复核，防误豁免真实失败）──
+known_failures:
+  - tests/some-old-stable-failure
+
+# ── worktree-guard 只读命令扩展（execute worktree 隔离期内放行额外只读命令）──
+worktree-hook:
+  readonlyCommands:
+    - rg
+    - fd
+
+# ── 变更规模自动分类（sillyspec run auto 时按需求描述强制 quick/full；正则数组，i 大小写无关）──
+auto_mode:
+  force_full_patterns:
+    - 数据库|migration
+  force_quick_patterns:
+    - fix typo
+`;
+}

package/src/db.js

@@ -202,7 +202,7 @@ export class DB {
       CREATE TABLE IF NOT EXISTS project (
         id INTEGER PRIMARY KEY DEFAULT 1,
         name TEXT NOT NULL,
-        schema_version INTEGER DEFAULT 4,
+        schema_version INTEGER DEFAULT 5,
         created_at TEXT NOT NULL,
         updated_at TEXT NOT NULL
       )

package/src/hooks/worktree-guard.js

@@ -356,9 +356,10 @@ function matchFileWhitelist(filePath) {
 }
 
 /**
- * 读取 local.yaml 中的扩展白名单配置（如果存在）
+ * 读取并解析 local.yaml（轻量手写解析，返回顶层对象）。
+ * 消费方读嵌套段 worktree-hook.readonlyCommands（见 isSingleCommandReadonly 的 extraReadonlyCommands）。
  * @param {string} cwd
- * @returns {{ fileWhitelist?: string[], readonlyCommands?: string[] }}
+ * @returns {Record<string, any>} 解析后的 local.yaml 顶层对象（文件缺/解析失败 → {}）
  */
 function loadLocalConfig(cwd) {
   const candidates = [

package/src/index.js

@@ -75,6 +75,7 @@ SillySpec CLI — 规范驱动开发工具包
     doctor [--fix] [--stale-hours N]    健康检查 + 修复
 
   sillyspec local detect [--dir <path>]   生成本地配置 local.yaml（纯 fs 嗅探，零 token、不跑 scan）
+  sillyspec config [schema] [--json]      打印 local.yaml 全部已知键 + 生效状态 + 读取点（堵外部 agent 配置发现缺口）
   sillyspec runtime list [--json]         枚举 .sillyspec/.runtime/ 运行时产物（只读，看手上有哪些证据/状态文件）
   sillyspec dispatch <probe | hint>       SillyHub 派发能力探测 + 策略生成（agent 调用桥，仅渲染不执行 tool）
 
@@ -1543,10 +1544,10 @@ SillySpec modules — 模块文档管理
       lines.push('# 测试策略：full=全量测试, module=只测变更模块, skip=跳过测试');
       lines.push('test_strategy: module');
       lines.push('');
-      lines.push('# 模块测试路径映射（可选）');
-      lines.push('# module_paths:');
-      lines.push('#   user-service: "user/"');
-      lines.push('#   order-service: "order/"');
+      lines.push('# monorepo 子模块映射（test_strategy: module 时按 git diff 命中模块收窄测试；inline flow 形态）');
+      lines.push('# modules:');
+      lines.push('#   user-service: { path: "user/", test: "cd user && npm test" }');
+      lines.push('#   order-service: { path: "order/", test: "cd order && npm test" }');
       lines.push('# 已知预存失败（可选）：verify 实测时这些失败被豁免、不阻断归档；fail-safe 仅豁免能检测到的失败行');
       lines.push('# known_failures:');
       lines.push('#   - "tests/test_legacy.py::test_old"');
@@ -1560,6 +1561,42 @@ SillySpec modules — 模块文档管理
       console.log(`   路径: ${localYamlPath}`);
       break;
     }
+    case 'config': {
+      // local.yaml 键发现缺口（2026-08-11）：键散落 ~10 个 reader，外部项目 agent 无从得知。
+      // config schema 把全部已知键 + 生效状态 + 读取点打印出来，堵住发现缺口。
+      // 数据源唯一 = src/config-schema.js（与 init 落盘的 local.yaml.example 同源）。
+      const configSub = filteredArgs[1];
+      const wantHelp = configSub === 'help' || configSub === '--help' || configSub === '-h';
+      const isSchema = !configSub || configSub === 'schema';
+      if (wantHelp) {
+        console.log(`
+SillySpec config — local.yaml 配置键速查
+
+用法:
+  sillyspec config                打印 local.yaml 全部已知键（人类可读树，默认）
+  sillyspec config schema         同上（显式子命令）
+  sillyspec config --json         机读 JSON（程序化消费）
+  sillyspec config schema --json  同上
+
+说明:
+  - 数据源：src/config-schema.js（唯一真相；reader 见各键「读取点」）
+  - 键分两类：【生效】配了即生效；【声明但未接线】代码/JSDoc 提及但无 reader，配了不生效
+  - 脱敏示例文件：sillyspec init 生成 local.yaml.example（可提交；真实 local.yaml 是 gitignored）
+`);
+        break;
+      }
+      if (!isSchema) {
+        const sug = didYouMean(configSub, ['schema']);
+        console.error(`❌ 未知子命令: config ${configSub}`);
+        if (sug) console.error(`   你是想输入「config ${sug}」吗？`);
+        console.error('用法: sillyspec config [schema] [--json]   打印 local.yaml 配置键');
+        process.exit(2);
+      }
+      const { renderSchemaHuman, renderSchemaJson } = await import('./config-schema.js');
+      if (json) console.log(renderSchemaJson());
+      else console.log(renderSchemaHuman());
+      break;
+    }
     case 'runtime': {
       // D2：.runtime/ 产物索引。CLI 往 .runtime/ 写各种证据/状态文件（db、doctor-diagnosis、
       // workflow-runs、user-inputs…），却没有命令让 agent 一眼看到「我手上有哪些产物」。

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 { renderExample } from './config-schema.js';
 // 向后兼容：getVersion 已抽到轻量 version.js（避免 index.js 为 --version 静态加载 init.js 的 inquirer 税），
 // 此处 re-export 保持 init.js 既有导出 API 不破坏（如 test/init-claude-injection.test.mjs）。
 export { getVersion };
@@ -313,6 +314,18 @@ function doInstall(projectDir, tools, subprojects = [], specDir = null) {
   const pm = new ProgressManager({ specDir: spec });
   pm.init(projectDir);
 
+  // 落盘脱敏 local.yaml.example（config-schema.js 单一数据源；不存在才写，仿 local detect skip-if-exists）
+  // 真实 local.yaml 是 gitignored 含凭据；example 可提交，是给人/外部 agent 看的配置发现物。
+  const examplePath = join(spec, 'local.yaml.example');
+  if (!existsSync(examplePath)) {
+    try {
+      writeFileSync(examplePath, renderExample());
+      console.log(chalk.green('    ✓ local.yaml.example 已生成（脱敏配置示例，可提交；真实 local.yaml 由 sillyspec local detect / platform connect 写入）'));
+    } catch (e) {
+      console.warn(chalk.yellow(`    ⚠ 生成 local.yaml.example 失败: ${e.message}`));
+    }
+  }
+
   // .gitignore 只在 specDir 在项目内时才修改
   const isExternalSpec = specDir && resolve(spec) !== resolve(projectDir, '.sillyspec');
  if (!isExternalSpec) {

package/src/run/command.js

@@ -1004,8 +1004,10 @@ async function runAutoMode(pm, progress, cwd, flags, changeName, platformOpts =
 
   // ── Classify change on first entry ──
   if (!progress.stages?.brainstorm?.status && !progress.stages?.plan?.status) {
-    const { classifyChange } = await import('../classify-change.js')
-    const classification = classifyChange({ description: inputText || '', explicitMode })
+    const { classifyChange, readAutoModeFromLocalYaml } = await import('../classify-change.js')
+    // auto_mode 接线（2026-08-11）：从 local.yaml 读 auto_mode 段传 localConfig，让 force_*_patterns 真生效。
+    const localConfig = readAutoModeFromLocalYaml(cwd)
+    const classification = classifyChange({ description: inputText || '', explicitMode, localConfig })
     if (classification.mode === 'quick') {
       console.log(`📊 auto 模式分类：${classification.mode}（${classification.reason}）`)
       console.log(`   此变更建议使用 quick 模式，运行：sillyspec run quick "${inputText || '需求'}"`)

package/src/run/prompt.js

@@ -41,9 +41,9 @@ function loadModuleContextIndex(specBase, projectName) {
     // 提示 v1/v2 格式混用风险（旧格式字段解析会静默错位）。正常生成的文件不触发。
     const sv = content.match(/^schema_version:\s*(\d+)/m)
     if (!sv) {
-      console.warn(`⚠️  _module-map.yaml 缺少 schema_version 声明（期望 2），模块解析可能错位：${mapPath}`)
+      console.warn(`⚠️  _module-map.yaml 缺少 schema_version 声明（期望 2），模块解析可能错位：${mapPath}（跑 \`sillyspec modules rebuild\` 升级到 schema_version: 2 可消除此警告）`)
     } else if (sv[1] !== '2') {
-      console.warn(`⚠️  _module-map.yaml schema_version=${sv[1]}（期望 2），可能为旧格式，模块解析可能错位：${mapPath}`)
+      console.warn(`⚠️  _module-map.yaml schema_version=${sv[1]}（期望 2），可能为旧格式，模块解析可能错位：${mapPath}（跑 \`sillyspec modules rebuild\` 升级到 schema_version: 2 可消除此警告）`)
     }
     return parseModuleMapSimple(content)
   } catch {
@@ -452,7 +452,13 @@ export async function outputStep(stageName, stepIndex, steps, cwd, changeName, d
       } catch {}
       if (!reviewRunId) {
         reviewRunId = generateStageReviewRunId()
-        try { mkdirSync(tierRuntimeRoot, { recursive: true }); writeFileSync(reviewRunIdMarker, reviewRunId + '\n') } catch {}
+        try {
+          mkdirSync(tierRuntimeRoot, { recursive: true })
+          writeFileSync(reviewRunIdMarker, reviewRunId + '\n')
+          // plan-c: echo 完整 review 目录路径，避免 agent 拿裸 runId 给子代理时漏连字符拼错路径
+          const reviewDir = `${tierRuntimeRoot}/stage-reviews/${stageName}-${reviewRunId}`
+          console.log(`  📁 Stage Review 写入目录（直接复制给 review 子代理，勿手拼 runId）：${reviewDir}/`)
+        } catch {}
       }
       // review.json 产物契约(schema + 示例 + docHash 算法 + 重算提示)事前注入,与 validateStageReviewSchema 同源
       const reviewContractMd = renderReviewJsonContract({ stage: stageName, changeDir: tierChangeDir, reviewRunId, tier: tier.tier })

package/src/run/quick-audit.js

@@ -24,9 +24,18 @@ export function printQuickAuditReview(review) {
     console.error(`\n   quick 已停止：请恢复/拆分这些变更，或重新运行 quick 并显式声明范围。`)
     // 解锁咒语须在 BLOCKED 分支也给出 —— 原只在 confirm/review 分支打印，
     // 普通 --done 走这里只看到「恢复/拆分」反方向指引，正确解法（带 flag 重跑）根本不出现。
-    console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
-    console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
-    console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+    // 但删除是例外：deletedFiles.length>0 是裸判定（auditQuickCompletion 判定行不受任何 flag
+    // 门控），--force-baseline / --allow-new 都救不回。此时甩 flag 建议会误导调用者照加后继续
+    // 被拦——改提示走完整流程 execute（有意设计：删除是高危操作，须 review 把关）。
+    if (review.deletedFiles && review.deletedFiles.length > 0) {
+      console.error(`\n   ⛔ 本次含删除文件 ${review.deletedFiles.length} 个：${review.deletedFiles.join(', ')}`)
+      console.error(`   quick 不支持删除——--force-baseline / --allow-new 均无法解锁（有意设计，高危操作须走 review 把关）。`)
+      console.error(`   请改走完整流程：sillyspec run execute（在 plan 的 task allowed_paths 内删除），或先 git restore 撤回删除后再 --done。`)
+    } else {
+      console.error(`   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
+      console.error(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
+      console.error(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+    }
   } else if (review.status === 'warning') {
     console.warn(`\n⚠️ quick 变更边界审计 — WARNING：`)
     for (const r of review.reasons) {

package/src/run/shared.js

@@ -655,10 +655,15 @@ export async function auditQuickCompletion(cwd, guard, options = {}) {
           console.log(`     - ${r}`)
         }
       }
-      console.log(`\n   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
-      console.log(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
-      console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
-      console.log(`   或在首个 sillyspec run quick 启动（step 1）时就声明这些 flag，持久化进 guard。`)
+      if (result.deletedFiles.length > 0) {
+        console.log(`\n   ⛔ 本次含删除文件 ${result.deletedFiles.length} 个——quick 不支持删除，--force-baseline / --allow-new 均无法解锁（有意设计，高危操作须走 review 把关）。`)
+        console.log(`     请改走完整流程：sillyspec run execute（在 plan 的 task allowed_paths 内删除），或先 git restore 撤回删除后再 --done。`)
+      } else {
+        console.log(`\n   如确认接受这些变更，重新运行 --done 时带上对应 flag 即可解锁：`)
+        console.log(`     sillyspec run quick --done --force-baseline --allow-new --change <id> --output "..."`)
+        console.log(`     （--force-baseline 覆盖受保护/危险文件如 src/run.js；--allow-new 允许新增文件）`)
+        console.log(`   或在首个 sillyspec run quick 启动（step 1）时就声明这些 flag，持久化进 guard。`)
+      }
     }
   } catch (e) {
     result.reasons.push(`审计失败: ${e.message}`)

package/src/stages/plan.js

@@ -425,6 +425,11 @@ related_tests:                           # 可选。当本 task 改动会导致
 
   const prompt = `为 plan.md 中的每个任务生成紧凑 TaskCard。
 
+⚠️ 生成卡片前先确认 plan.md 已满足（否则下一步 postcheck 会硬拦，导致返工重编号/重分 Wave）：
+- **共享文件须分 Wave**：若多个 task 的 allowed_path 含同一文件，plan.md 必须把它们分到不同「## Wave N」（同 Wave 共享文件会被 execute 强制并行，子代理互相覆盖；postcheck 拦同 Wave 共享）
+- **task id 从 1 连续**：task-01、task-02、task-03… 不能跳号或重号（postcheck 校验 id 连续性，gap 会拦）
+这两条是跨 task 全局约束，子代理只写单卡看不到全局——你（主 agent）分派子代理前必须先在 plan.md 里确认 Wave 划分与编号正确。
+
 ## 任务清单
 ${taskList}
 

package/src/sync.js

@@ -40,8 +40,13 @@ const DOCUMENT_FILES = ['proposal.md', 'design.md', 'requirements.md', 'tasks.md
 // ── YAML 辅助 ──
 
 /**
- * 简易 YAML 读写，只处理 project 段的扁平结构。
+ * 简易 YAML 读取（解析为扁平 obj），供 _getPlatform / status 只读用。
  * 与 worktree-guard.js 的 parseSimpleYaml 保持一致的轻量风格。
+ *
+ * 写入侧（connect/disconnect）**不再**走 parse→modify→write 有损往返——
+ * readLocalYaml/parseSimpleYaml 丢注释（:85 跳 # 行）、丢数组/深嵌套（只认一层 key:value），
+ * round-trip 会清空用户手填的注释与其他段。改为 readLocalYamlRaw + replaceTopLevelSection
+ * 文本级定向替换 platform 段，原文件注释/空行/其他段/数组/深嵌套/CRLF 字节级保留。
  */
 function readLocalYaml(cwd) {
   const p = join(cwd, LOCAL_YAML);
@@ -53,28 +58,81 @@ function readLocalYaml(cwd) {
   }
 }
 
-function writeLocalYaml(cwd, obj) {
-  const dir = join(cwd, '.sillyspec');
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  const lines = [];
-  const rootKeys = Object.keys(obj);
-  for (const key of rootKeys) {
-    const val = obj[key];
-    if (val === null || val === undefined) continue;
-    if (typeof val === 'object' && !Array.isArray(val)) {
-      lines.push(`${key}:`);
-      for (const [k, v] of Object.entries(val)) {
-        if (typeof v === 'string') {
-          lines.push(`  ${k}: ${v}`);
-        } else {
-          lines.push(`  ${k}: ${JSON.stringify(v)}`);
-        }
-      }
-    } else {
-      lines.push(`${key}: ${typeof val === 'string' ? val : JSON.stringify(val)}`);
+/** 读 local.yaml 原始文本（保留注释/换行/结构），不存在返回 ''。供 connect/disconnect 文本级改写。 */
+function readLocalYamlRaw(cwd) {
+  const p = join(cwd, LOCAL_YAML);
+  if (!existsSync(p)) return '';
+  try {
+    return readFileSync(p, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 定位顶层 YAML 段（如 platform:/mcp:）的行范围 [start, end)。
+ * 段 = key 行（行首非空白 + 以 'name:' 开头）+ 后续连续缩进行（以空格/tab 开头）。
+ * 遇空行/注释/下一个顶层 key 即段结束——这些行不属于本段，保留不动。
+ * split('\n')/join('\n') 操作：CRLF 下 '\r' 留在行尾，重组原样还原（Windows 兼容，CLAUDE.md #13）。
+ * @param {string} text
+ * @param {string} name - 段名（不含冒号，如 'platform'）
+ * @returns {{start: number, end: number} | null} 不存在返回 null
+ */
+function findTopLevelSectionRange(text, name) {
+  const lines = text.split('\n');
+  const prefix = `${name}:`;
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // 顶层 key 行：行首非空白（排除缩进子段）+ 以 'name:' 开头
+    if (/^\S/.test(line) && line.startsWith(prefix)) {
+      start = i;
+      break;
     }
   }
-  writeFileSync(join(cwd, LOCAL_YAML), lines.join('\n') + '\n', 'utf8');
+  if (start === -1) return null;
+  let end = start + 1;
+  while (end < lines.length && /^[ \t]/.test(lines[end])) {
+    end++;
+  }
+  return { start, end };
+}
+
+/**
+ * 文本级定向替换/删除/追加一个顶层 YAML 段，保留文件其余所有字节
+ * （注释/空行/其他段/数组/深嵌套/CRLF 全保留）。
+ * @param {string} text - 原始文件文本
+ * @param {string} name - 段名（不含冒号）
+ * @param {string|null} body - 段体（不含 key 行）；null=删除该段；string=替换或追加
+ * @returns {string} 新文本
+ */
+function replaceTopLevelSection(text, name, body) {
+  const lines = text.split('\n');
+  const range = findTopLevelSectionRange(text, name);
+  if (range) {
+    const before = lines.slice(0, range.start);
+    const after = lines.slice(range.end);
+    if (body === null) {
+      return [...before, ...after].join('\n');
+    }
+    const sectionLines = [`${name}:`, ...body.split('\n')];
+    return [...before, ...sectionLines, ...after].join('\n');
+  }
+  // 段不存在
+  if (body === null) return text; // 删不存在的段，原样返回
+  // 追加：去尾换行后加空行分隔 + 新段；空文件直接起段
+  const stripped = text.replace(/(\r?\n)+$/, '');
+  if (stripped === '') {
+    return `${name}:\n${body}\n`;
+  }
+  return `${stripped}\n\n${name}:\n${body}\n`;
+}
+
+/** 文本级写 local.yaml（保留传入 text 的注释/结构）；确保 .sillyspec 目录存在。 */
+function writeLocalYamlRaw(cwd, text) {
+  const dir = join(cwd, '.sillyspec');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(cwd, LOCAL_YAML), text, 'utf8');
 }
 
 function parseSimpleYaml(content) {
@@ -201,7 +259,8 @@ export class SyncManager {
    */
   async connect(url, token, user) {
     // 验证连接
-    const healthUrl = `${url.replace(/\/+$/, '')}/api/health`;
+    const normalizedUrl = url.replace(/\/+$/, '');
+    const healthUrl = `${normalizedUrl}/api/health`;
     const result = await fetchJson(healthUrl);
     if (result === null) {
       console.warn(`[sync] 平台连接验证失败: ${url}`);
@@ -212,21 +271,23 @@ export class SyncManager {
     // 解析推送者身份（D-004）：显式 > git user.name > env；全失败留空不写 user 字段
     const resolvedUser = resolvePlatformUser(this.cwd, user);
 
-    // 写入 local.yaml
-    const config = readLocalYaml(this.cwd);
-    config.platform = {
-      url: url.replace(/\/+$/, ''),
-      token,
-      last_connected: new Date().toISOString(),
-    };
+    // 文本级改写 local.yaml：定向替换 platform 段，原文件注释/其他段/数组/深嵌套/CRLF 字节级保留
+    // （旧 read-modify-write 经 parseSimpleYaml 丢注释+丢非扁平结构，round-trip 清空用户手填内容）。
+    const platformEntries = [
+      `  url: ${normalizedUrl}`,
+      `  token: ${token}`,
+      `  last_connected: ${new Date().toISOString()}`,
+    ];
     if (resolvedUser) {
-      config.platform.user = resolvedUser;
+      platformEntries.push(`  user: ${resolvedUser}`);
     }
-    // mcp 段同源假设（design §7.4）：复用 platform 的 url/token；用户已手填 mcp 段则保留不覆盖（R-09）
-    if (!config.mcp) {
-      config.mcp = { url: url.replace(/\/+$/, ''), token };
+    let text = readLocalYamlRaw(this.cwd);
+    text = replaceTopLevelSection(text, 'platform', platformEntries.join('\n'));
+    // mcp 段同源假设（design §7.4）：复用 platform 的 url/token；用户已手填 mcp 段则保留不覆盖（R-09，文本级检测）
+    if (findTopLevelSectionRange(text, 'mcp') === null) {
+      text = replaceTopLevelSection(text, 'mcp', `  url: ${normalizedUrl}\n  token: ${token}`);
     }
-    writeLocalYaml(this.cwd, config);
+    writeLocalYamlRaw(this.cwd, text);
   }
 
   /**
@@ -239,17 +300,18 @@ export class SyncManager {
       console.log('[sync] 已断开连接（无配置文件）');
       return;
     }
-    const config = readLocalYaml(this.cwd);
-    if (!config.platform) {
+    const text = readFileSync(p, 'utf8');
+    if (findTopLevelSectionRange(text, 'platform') === null) {
       console.log('[sync] 已断开连接（未连接）');
       return;
     }
-    delete config.platform;
-    if (Object.keys(config).length === 0) {
-      // 配置为空，删除整个文件
+    // 文本级删除 platform 段，保留注释/其他段/数组/深嵌套/CRLF
+    const newText = replaceTopLevelSection(text, 'platform', null);
+    if (newText.trim() === '') {
+      // 删段后纯空白（无任何段也无注释）→ 删除整个文件；注释算内容，有注释则保留
       try { unlinkSync(p); } catch { /* best effort */ }
     } else {
-      writeLocalYaml(this.cwd, config);
+      writeFileSync(p, newText, 'utf8');
     }
     console.log('[sync] 已断开连接');
   }