sillyspec 3.26.0 → 3.26.2

package/src/db.js

@@ -1,13 +1,13 @@
-import Database from 'better-sqlite3';
+import { openDatabase, applyPragmas, runTransaction } from './db-engine.js';
 import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { dirname } from 'path';
 
 // DB schema 版本（与 project.schema_version DEFAULT 对齐）。_createSchema 改动（加表/列/migration）时 bump，
 // 触发 .schema-version 戳失效 → 下次 init 重跑 _createSchema（W4-H：高频读路径 gate/derive/status
 // 每次 new ProgressManager 都过 init，靠版本戳跳过建表省开销）。
-// better-sqlite3 是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
+// node:sqlite（DatabaseSync）是原生 SQLite 引擎，打开即持久化（不像 sql.js 纯内存需整库 export 落盘），
 // _createSchema 内 DDL 直接落盘，无需额外 _save。
-const DB_SCHEMA_VERSION = 4;
+const DB_SCHEMA_VERSION = 5;
 
 // SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）：WAL 单写者模型，并发写第二者在
 // busy_timeout=5000（init PRAGMA）后抛 SQLITE_BUSY。busy_timeout 已在引擎层处理大部分等待；
@@ -20,7 +20,7 @@ const MAX_BUSY_RETRIES = 3;
 const BUSY_BACKOFF_MS = [50, 100, 200];
 
 /**
- * 同步阻塞 sleep（better-sqlite3 同步 API，BUSY 退避不能用 await）。
+ * 同步阻塞 sleep（node:sqlite 同步 API，BUSY 退避不能用 await）。
  * Atomics.wait 阻塞当前线程不占 CPU；SharedArrayBuffer 不可用的环境（受限 CSP / 旧 Node）
  * 退化为 busy-wait（退避时长 50-200ms 短，CPU 占用可接受）。仅在 transaction() 的 BUSY
  * 重试路径调用。
@@ -41,13 +41,13 @@ export class DB {
   }
 
   /**
-   * 同步初始化（better-sqlite3 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
-   *  - new Database(path) 同步打开/创建库文件（better-sqlite3 原生绑定，非 WASM）
-   *  - PRAGMA：journal_mode=WAL 真生效（better-sqlite3 直连原生 SQLite，WAL 落地；
+   * 同步初始化（node:sqlite DatabaseSync 是同步 API，无 async/await，与 sql.js 的 initSqlJs() 异步加载不同）：
+   *  - openDatabase(path) 同步打开/创建库文件（node:sqlite 原生绑定，非 WASM）
+   *  - PRAGMA：journal_mode=WAL 真生效（node:sqlite 直连原生 SQLite，WAL 落地；
    *    sql.js 是纯内存库，WAL 对它无意义），busy_timeout=5000 让写锁竞争时自动等待，
    *    foreign_keys=ON 启用外键级联，synchronous=NORMAL 在 WAL 下兼顾安全与性能
    *  - schema 戳检查：内容匹配 DB_SCHEMA_VERSION 则跳过 _createSchema，省建表开销
-   *  - better-sqlite3 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
+   *  - node:sqlite 打开即持久化，DDL/事务提交直接落盘，不需要 sql.js 时代的 _save()
    *
    * .bak 损坏回退由 _openWithFallback() 承担（task-04）：主库 → .bak → 全新/报错 逐级回退，
    * 语义对齐原 sql.js 的 _loadDatabase。
@@ -60,14 +60,16 @@ export class DB {
     // 2. 同步打开/创建数据库（主库 → .bak → 全新/报错 逐级回退，归 task-04）
     this.db = this._openWithFallback();
 
-    // 3. 设置 PRAGMA（better-sqlite3 走真 SQLite，journal_mode=WAL 真生效）
-    this.db.pragma('journal_mode = WAL');
-    this.db.pragma('busy_timeout = 5000');
-    this.db.pragma('foreign_keys = ON');
-    this.db.pragma('synchronous = NORMAL');
+    // 3. 设置 PRAGMA（node:sqlite 走真 SQLite，journal_mode=WAL 真生效；经 applyPragmas 逐条 exec）
+    applyPragmas(this.db, [
+      ['journal_mode', 'WAL'],
+      ['busy_timeout', '5000'],
+      ['foreign_keys', 'ON'],
+      ['synchronous', 'NORMAL'],
+    ]);
 
     // 4. 创建表结构（仅当 schema 版本戳不匹配时——W4-H）：
-    //    schema 已最新则跳过建表，省 DDL 开销。better-sqlite3 打开即持久化，
+    //    schema 已最新则跳过建表，省 DDL 开销。node:sqlite 打开即持久化，
     //    _createSchema 内 DDL 直接落盘，无需 _save。
     //    戳在但 db 缺表属"手动改 db"边角（SillySpec 不支持），不在本层兜底。
     const versionPath = `${this.dbPath}.schema-version`;
@@ -85,13 +87,13 @@ export class DB {
 
   /**
    * 打开数据库（主库 → .bak → 全新/报错 逐级回退）。
-   * 语义对齐原 sql.js 的 _loadDatabase，但 better-sqlite3 绑定文件路径无 _save，
+   * 语义对齐原 sql.js 的 _loadDatabase，但 node:sqlite 绑定文件路径无 _save，
    * .bak 回退时 copyFileSync 把 .bak 内容恢复到主库路径，统一用 dbPath。
    *  - 主库存在且有内容且可打开：直接用。
    *  - 主库缺失/为空/损坏：尝试 .bak；成功则 warn 原因后 copy 回主库使用。
    *  - 都不可用：主库不存在→建全新空库；主库曾存在(空/损坏)→fail-loud 抛错(不静默建空库吞进度)。
-   * better-sqlite3 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
-   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——better-sqlite3 视其为合法空库，
+   * node:sqlite 打开 0 字节文件不抛错：主库须 statSync 显式判空（截断信号→走回退，防静默吞进度）；
+   * .bak 作为恢复源只要存在且能打开即用（含 0 字节空库——node:sqlite 视其为合法空库，
    * 生产环境 .bak 由原子写改名上一完整主库得来，永不为 0 字节，0 字节态仅出现在测试构造）。
    */
   _openWithFallback() {
@@ -101,10 +103,10 @@ export class DB {
       if (!existsSync(p)) return null;
       return statSync(p).size === 0 ? 'empty' : 'ok';
     };
-    // tryOpen: new Database(path) + prepare 探测双保险（防打开成功但内容非 SQLite）
+    // tryOpen: openDatabase(path) + prepare 探测双保险（防打开成功但内容非 SQLite）
     const tryOpen = (p) => {
       let db;
-      try { db = new Database(p); }
+      try { db = openDatabase(p); }
       catch { return null; }
       try { db.prepare('SELECT count(*) FROM sqlite_master').get(); return db; }
       catch { try { db.close(); } catch { /* 关闭失败忽略 */ } return null; }
@@ -117,7 +119,7 @@ export class DB {
     }
 
     // 2. .bak 回退（.bak 是恢复源：存在且能打开即用，含 0 字节空库；门禁只挡"不存在"，
-    //    避免 tryOpen 对不存在的路径触发 new Database 的副作用——会凭空创建文件）
+    //    避免 tryOpen 对不存在的路径触发 openDatabase 的副作用——会凭空创建文件）
     if (readValid(bakPath) !== null) {
       const bakDb = tryOpen(bakPath);
       if (bakDb) {
@@ -129,23 +131,23 @@ export class DB {
             : 'sillyspec.db 损坏';
         console.warn(`⚠️  ${reason}，已从 .bak 备份恢复。`);
         bakDb.close();
-        // better-sqlite3 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
+        // node:sqlite 绑定路径，无 _save：把 .bak 内容 copy 回主库，统一用 dbPath
         copyFileSync(bakPath, this.dbPath);
-        return new Database(this.dbPath);
+        return openDatabase(this.dbPath);
       }
     }
 
     // 3. 都不可用
     if (readValid(this.dbPath) === null) {
       // 主库与备份都不存在 → 全新项目，建空库
-      return new Database(this.dbPath);
+      return openDatabase(this.dbPath);
     }
     // 主库曾存在（空/损坏）但无法恢复 → 数据丢失，必须 fail-loud（不静默建空库吞进度）
     throw new Error('sillyspec.db 损坏且 .bak 备份不可用，无法恢复。请从版本控制或其他备份恢复 .sillyspec/.runtime/ 后重试。');
   }
 
   /**
-   * 关闭数据库。better-sqlite3 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
+   * 关闭数据库。node:sqlite 的 close() 自动做 WAL checkpoint（把 -wal/-shm 日志合并回主库），
    * 不需要 sql.js 时代的 _save() 整库 export 落盘。
    */
   close() {
@@ -158,9 +160,10 @@ export class DB {
   /**
    * 原生事务 + SQLITE_BUSY 应用层有限重试（R-08 / NFR-03）。
    *
-   * better-sqlite3 的 db.transaction(fn) 返回一个包装函数，调用时自动
-   * BEGIN/COMMIT/ROLLBACK（fn 抛错自动 ROLLBACK 且不吞错），嵌套调用自动用 SAVEPOINT。
-   * 无需手动 BEGIN/COMMIT/ROLLBACK，也无需 _save（better-sqlite3 提交即持久化）。
+   * node:sqlite 无 .transaction()，runTransaction(fn)（db-engine）用 SAVEPOINT/RELEASE/
+   * ROLLBACK TO 手写事务：fn 抛错自动回滚且不吞错，嵌套调用自动形成 savepoint 栈
+   * （对齐旧引擎嵌套自动 SAVEPOINT 的兼容实现）。无需手动 BEGIN/COMMIT/ROLLBACK，
+   * 也无需 _save（node:sqlite 提交即持久化）。
    *
    * SQLITE_BUSY 重试：WAL 单写者模型，并发写第二者在 busy_timeout=5000 后抛 BUSY。此处对
    * BUSY 加 MAX_BUSY_RETRIES 次递增退避（BUSY_BACKOFF_MS）；仅 BUSY 重试（其它异常直接上抛），
@@ -169,14 +172,13 @@ export class DB {
    */
   transaction(fn) {
     if (!this.db) throw new Error('DB not initialized');
-    const tx = this.db.transaction(fn);
     let attempt = 0;
     while (true) {
       try {
-        return tx();
+        return runTransaction(this.db, fn);
       } catch (err) {
-        // 仅 SQLITE_BUSY 重试（better-sqlite3 err.code 为 'SQLITE_BUSY'/5，message 含 'database is locked'）
-        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5
+        // 仅 SQLITE_BUSY 重试（node:sqlite err.errcode 为 5 / err.code 为 'ERR_SQLITE_ERROR'，message 含 'database is locked'）
+        const isBusy = err && (err.code === 'SQLITE_BUSY' || err.code === 5 || err.errcode === 5
           || (typeof err.message === 'string' && /database is locked|SQLITE_BUSY/i.test(err.message)));
         if (!isBusy) throw err;
         if (attempt >= MAX_BUSY_RETRIES) throw err; // 达上限 fail-loud（不静默吞，防死循环）
@@ -186,13 +188,13 @@ export class DB {
     }
   }
 
-  /** 获取底层 db 对象（better-sqlite3 Database 实例，供 progress.js 直接使用） */
+  /** 获取底层 db 对象（node:sqlite DatabaseSync 实例，供 progress.js 直接使用） */
   getDb() {
     return this.db;
   }
 
   _createSchema() {
-    // better-sqlite3：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
+    // node:sqlite：exec() 执行多条 SQL/DDL（无返回）；prepare().run/get/all 用于 DML。
     // sql.js 的 .run(sql) 在此换为 .exec(sql)。
 
     // project 表
@@ -200,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
       )
@@ -310,11 +312,19 @@ export class DB {
     // last_synced_platform_ts NULL=首次同步（base_ts NULL 平台接受首次 push）。
     this._migrateAddColumn('changes', 'last_synced_platform_ts', 'TEXT');
     this._migrateAddColumn('changes', 'last_local_modified_ts', 'TEXT');
+
+    // changes 表加 title（人类可读中文标题）+ quicklog_id（关联 QUICKLOG ql-ID）两列：
+    // 让 quick-<hex> 这种机器 hash sessionId 命名的 change 行可读，DB↔QUICKLOG 可对账。
+    // quick 启动时回填（stage.js：title 从任务描述提取、quicklog_id 用分配的 qlId），
+    // --done 时从 step3「需求：」刷新 title（agent 可改）。完整流程 change 的 name 本身
+    // 已语义化，title/quicklog_id 留空。不纳入平台同步脏度（本地展示用元信息）。
+    this._migrateAddColumn('changes', 'title', 'TEXT');
+    this._migrateAddColumn('changes', 'quicklog_id', 'TEXT');
   }
 
   /**
    * 幂等地给表添加列（列已存在则跳过）。
-   * better-sqlite3：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
+   * node:sqlite：exec() 执行 ALTER TABLE DDL；列已存在抛错被 catch 静默跳过。
    * @private
    */
   _migrateAddColumn(table, column, type) {

package/src/doctor-diagnostics.js

@@ -11,7 +11,7 @@
  *     - safe_actions：只描述建议动作与风险等级，绝不自动执行
  *
  * 安全约束（硬性）：
- *   - 所有检测只读。DB 以 better-sqlite3 只读连接打开（readonly + fileMustExist），不调用
+ *   - 所有检测只读。DB 以 node:sqlite 只读连接打开（readOnly + existsSync 前置门），不调用
  *     export/writeFileSync，不跑建表/迁移，close 后丢弃——绝不写回原 db 文件。
  *   - 不删除/移动任何文件；orphan db 仅报告，处理交给后续 --dump-db / --confirm 流程。
  *   - execute-progress-plan-mismatch 维度同样只读：仅读 plan.md checkbox + 只读查 stages 表，
@@ -20,7 +20,7 @@
  * 风格对齐 scan-postcheck.js：checks 用 CHECK_SEVERITY，formatter 产出 schema_version JSON，
  * writer 落盘到 <authoritySpecDir>/.runtime/。
  */
-import Database from 'better-sqlite3';
+import { openDatabase, pluckGet, pluckAll } from './db-engine.js';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { CHECK_SEVERITY } from './constants.js';
@@ -68,16 +68,16 @@ function probeDb(dbPath) {
   }
   let db = null;
   try {
-    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db = openDatabase(dbPath, { readOnly: true });
     const pick = (sql, fallback = null) => {
       try {
-        const r = db.prepare(sql).pluck().get();
+        const r = pluckGet(db, sql);
         return r === undefined ? fallback : r;
       } catch { return fallback; }
     };
     const pickCol = (sql) => {
       try {
-        return db.prepare(sql).pluck().all();
+        return pluckAll(db, sql);
       } catch { return []; }
     };
     // 每个 active change 的 execute stage status（只读查询；stages 表的 status 列）。
@@ -657,7 +657,7 @@ export async function dumpDb({ dbPath, cwd }) {
   }
   let db = null;
   try {
-    db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    db = openDatabase(dbPath, { readOnly: true });
     const rows = (sql) => {
       try { return db.prepare(sql).all(); } catch { return []; }
     };

package/src/hooks/worktree-guard.js

@@ -12,7 +12,6 @@
 import { existsSync, readFileSync, readdirSync } from 'fs'
 import path from 'path'
 import { execFileSync } from 'child_process'
-import { createRequire } from 'module'
 
 // ── 常量 ──
 
@@ -225,20 +224,19 @@ function isInsideWorktreeStorage(filePath, cwd) {
 /**
  * 同步只读查询 sillyspec.db 第一行第一列（不依赖外部 sqlite3 CLI）。
  *
- * 用子进程跑 better-sqlite3 同步原生绑定（execFileSync 等待）：
- * - 原生绑定经 hook 进程的 createRequire(import.meta.url).resolve('better-sqlite3') 解析出绝对路径，
- *   JSON.stringify 嵌入子进程脚本——子进程 cwd 是项目目录，裸 require('better-sqlite3') 找不到包
- *   （用户项目未必直接装了它）；绝对路径 Windows/Linux/macOS 均 require 直接可用，无需 file:// URL。
- * - readonly + fileMustExist 双 true 打开只读连接：绝不写库；WAL 并发读不阻塞主进程写，
- *   且原生绑定可看到已 commit 但未 checkpoint 的过渡态（修复旧 WASM 内存库裸读 .db
- *   看不见 WAL 的过渡态可见性窗口）。
+ * 用子进程跑 node:sqlite 的 DatabaseSync（execFileSync 等待）：
+ * - node:sqlite 是 Node 内置模块，子进程 require('node:sqlite') 直接可用，无需先 resolve 出
+ *   绝对路径再注入（旧方案需手动解析原生绑定路径，node:sqlite 无此步骤）。
+ * - readOnly 打开只读连接（替代旧方案 readonly/fileMustExist 语义）：绝不写库；WAL 并发读不阻塞主进程写，
+ *   且只读连接可看到已 commit 但未 checkpoint 的过渡态（修复旧 WASM 内存库裸读 .db
+ *   看不见 WAL 的过渡态可见性窗口）。db 缺失/损坏由 open 异常自然触发 fail-closed（外层 catch）。
  *
  * 环境假设（R-09）：WAL 模式下只读连接仍需在 .runtime/ 目录建/更新 -shm 索引文件，故 .runtime
  * 必须可写（与主进程一致）——“只读”指不改 DB 数据，不等于不对 -shm 加索引。
  *
- * fail-closed：better-sqlite3 resolve 失败 / db 文件不存在 / fileMustExist 打开失败 / 查询异常 /
- * 子进程超时或崩溃——一律 console.warn（含 e.stderr 详情）并返回 null，调用方
- *（readCurrentStage/isNoWorktreeMode）对 null 走 fail-closed，禁止 fail-open。
+ * fail-closed：db 文件不存在 / 子进程打开、查询异常 / 子进程超时或崩溃——一律 console.warn
+ * （含 e.stderr 详情）并返回 null，调用方（readCurrentStage/isNoWorktreeMode）对 null 走
+ * fail-closed，禁止 fail-open。
  */
 function queryDbFirstCell(cwd, sql) {
   const dbPath = path.join(cwd, '.sillyspec', '.runtime', 'sillyspec.db')
@@ -248,21 +246,15 @@ function queryDbFirstCell(cwd, sql) {
     console.warn('⚠️ sillyspec.db 不存在，hook 降级 fail-closed: ' + dbPath)
     return null
   }
-  let libPath
-  try {
-    libPath = createRequire(import.meta.url).resolve('better-sqlite3')
-  } catch (e) {
-    console.warn('⚠️ sillyspec.db 查询失败（better-sqlite3 未解析），hook 降级 fail-closed: ' + ((e && e.message) || e))
-    return null
-  }
-  // 子进程同步 require 绝对路径（better-sqlite3 是同步原生 API，无 async/import().then 包装）。
-  // pluck().get() 取第一行第一列原值，无行返回 undefined（写空 stdout → 父侧 trim 后 null）。
+  // 子进程同步内置 require('node:sqlite')（DatabaseSync 是同步 API，无 async/import().then 包装）。
+  // prepare(sql).get() 取第一行整行后取首列值，无行返回 undefined（写空 stdout → 父侧 trim 后 null）。
   const script =
-    "const D=require(" + JSON.stringify(libPath) + ")," +
+    "const {DatabaseSync}=require('node:sqlite')," +
     "dbPath=" + JSON.stringify(dbPath) + ",sql=" + JSON.stringify(sql) + ";" +
     "let db;" +
-    "try{db=new D(dbPath,{readonly:true,fileMustExist:true});" +
-    "const v=db.prepare(sql).pluck().get();" +
+    "try{db=new DatabaseSync(dbPath,{readOnly:true});" +
+    "const row=db.prepare(sql).get();" +
+    "const v=row===undefined?undefined:Object.values(row)[0];" +
     "if(v!==undefined)process.stdout.write(String(v??''));db.close()}" +
     "catch(e){process.stderr.write('hook db query failed: '+String(e&&e.message||e));process.exit(1)};"
   try {
@@ -270,7 +262,7 @@ function queryDbFirstCell(cwd, sql) {
       encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'pipe'],
     }).trim() || null
   } catch (e) {
-    // DB 查询失败（db 损坏 / fileMustExist 打开失败 / 子进程超时或崩溃）：降级返回 null，调用方
+    // DB 查询失败（db 损坏 / readOnly 打开失败 / 子进程超时或崩溃）：降级返回 null，调用方
     //（readCurrentStage 等）对 null 走 fail-closed。补 warn 让 doctor/agent 能看到根因，
     // 而非完全静默（子进程把诊断写到了 stderr，execFileSync 抛错时挂在 e.stderr 上）。
     const detail = (e && e.stderr ? String(e.stderr).trim() : '') || (e && e.message) || 'timeout/crash'
@@ -291,7 +283,7 @@ export {
  * @returns {string|null} 阶段名，null 表示无法确定
  */
 function readCurrentStage(cwd) {
-  // 直读 sillyspec.db（node + better-sqlite3 只读子进程，不依赖外部 sqlite3 CLI——Windows 默认没有）
+  // 直读 sillyspec.db（node + node:sqlite 只读子进程，不依赖外部 sqlite3 CLI——Windows 默认没有）
   const v = queryDbFirstCell(cwd, "SELECT current_stage FROM changes WHERE status='active' AND current_stage IN ('execute','quick') ORDER BY last_active DESC LIMIT 1")
   return v || null
 }
@@ -302,7 +294,7 @@ function readCurrentStage(cwd) {
  * @returns {boolean}
  */
 function isNoWorktreeMode(cwd) {
-  // 直读 sillyspec.db（node + better-sqlite3，同 readCurrentStage）
+  // 直读 sillyspec.db（node + node:sqlite，同 readCurrentStage）
   return queryDbFirstCell(cwd, "SELECT no_worktree FROM changes WHERE status='active' AND current_stage IN ('execute','quick') LIMIT 1") === '1'
 }
 
@@ -364,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/progress/change-registry.js

@@ -67,6 +67,34 @@ export class ChangeRegistry {
     }
   }
 
+  /**
+   * 更新变更的人类可读元信息（title / quicklog_id），让 quick-<hex> 行可读、DB↔QUICKLOG 可对账。
+   * quick 启动时回填（title 从任务描述、quicklog_id 用分配的 qlId）；--done 时从 step3「需求：」刷新 title。
+   * 部分更新（只传 title 不动 quicklog_id，反之亦然）。不调 _touchLocalModified：title/quicklog_id 是
+   * 本地展示用元信息，纳入脏度会扰动平台同步（平台 changes 表无此列）。
+   * @param {string} cwd
+   * @param {string} changeName
+   * @param {{ title?: string, quicklogId?: string }} meta
+   */
+  updateChangeMeta(cwd, changeName, meta) {
+    if (!changeName || !meta) return;
+    const db = this.pm._ensureDB(cwd);
+    try {
+      db.transaction(() => {
+        const sqlDb = db.getDb();
+        const sets = [];
+        const params = [];
+        if (meta.title !== undefined) { sets.push('title = ?'); params.push(meta.title); }
+        if (meta.quicklogId !== undefined) { sets.push('quicklog_id = ?'); params.push(meta.quicklogId); }
+        if (sets.length === 0) return;
+        params.push(changeName);
+        sqlDb.prepare(`UPDATE changes SET ${sets.join(', ')} WHERE name = ?`).run(...params);
+      });
+    } catch (err) {
+      console.warn('⚠️  更新 change 元信息失败:', err.message);
+    }
+  }
+
   /**
    * 读取变更的隔离状态
    * @param {string} cwd - 项目根目录

package/src/progress/shared.js

@@ -27,7 +27,7 @@ export const STAGE_ORDER = ['scan', 'brainstorm', 'plan', 'execute', 'verify', '
 export const MAIN_FLOW_ORDER = ['brainstorm', 'plan', 'execute', 'verify', 'archive'];
 
 // progress 数据版本（v3 = SQLite；v4 = changes 加 base_ts / 本地脏度两列，platform-sync §8）
-export const CURRENT_VERSION = 4;
+export const CURRENT_VERSION = 5;
 
 // 空阶段骨架
 export function emptyStage() {

package/src/progress.js

@@ -347,7 +347,7 @@ export class ProgressManager {
     }
 
     const result = {
-      _version: 4,
+      _version: 5,
       project: projectName,
       currentChange: cName,
       currentStage: currentStage || '',
@@ -776,6 +776,8 @@ export class ProgressManager {
 
   unregisterChange(cwd, changeName) { return this._changeRegistry.unregisterChange(cwd, changeName); }
 
+  updateChangeMeta(cwd, changeName, meta) { return this._changeRegistry.updateChangeMeta(cwd, changeName, meta); }
+
   // ── CLI 命令 ──
 
   init(cwd) {
@@ -815,7 +817,7 @@ export class ProgressManager {
    * 初始化指定变更的 progress
    * SQL: INSERT changes + 批量 INSERT stages
    */
-  initChange(cwd, changeName) {
+  initChange(cwd, changeName, meta = {}) {
     if (!changeName) {
       console.warn('⚠️  initChange: changeName 为空，跳过');
       return null;
@@ -836,9 +838,9 @@ export class ProgressManager {
       if (existing === undefined) {
         // 插入 changes 行
         sqlDb.prepare(
-          `INSERT INTO changes (name, current_stage, status, created_at, last_active)
-           VALUES (?, 'scan', 'active', ?, ?)`
-        ).run(changeName, now, now);
+          `INSERT INTO changes (name, current_stage, status, created_at, last_active, title, quicklog_id)
+           VALUES (?, 'scan', 'active', ?, ?, ?, ?)`
+        ).run(changeName, now, now, meta.title || null, meta.quicklogId || null);
       }
 
       // 获取 change_id

package/src/quicklog.js

@@ -75,7 +75,7 @@ function nowDatetime(d = new Date()) {
 }
 
 // 描述压成一行、限长，避免破坏 QUICKLOG 条目结构
-function sanitizeDesc(description) {
+export function sanitizeDesc(description) {
   const s = String(description || '').replace(/[\r\n]+/g, ' ').trim()
   if (!s) return '(quick 任务)'
   return s.length > 120 ? s.slice(0, 120) + '…' : s
@@ -101,7 +101,7 @@ export function deriveTitleFromLinkedChange(specBase, change) {
 
 // 从 quick step3 --output 四字段提取「需求：」摘要，用于翻完成时刷新标题行
 // （覆盖启动时的占位/弱标题）。提取失败返回 ''（不刷新）。
-function extractTitleFromResult(result) {
+export function extractTitleFromResult(result) {
   if (!result) return ''
   const m = String(result).match(/需求：([^\n\r]*?)(?:\s+根因：|$)/)
   if (!m) return ''

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/complete-handlers.js

@@ -30,7 +30,7 @@ import { detectConcurrentChanges, formatConcurrentWarning } from './concurrent-d
 import { stageRegistry } from '../stages/index.js'
 import { SCAN_STATUS, POINTER_STATUS } from '../constants.js'
 import { printQuickAuditReview } from './quick-audit.js'
-import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry } from '../quicklog.js'
+import { validateQuickResult, allocateQuicklogEntry, findQuicklogEntry, completeQuicklogEntry, extractTitleFromResult } from '../quicklog.js'
 import { getRule } from '../stage-contract-spec.js'
 import { archiveDestDirName } from '../stage-contract.js'
 
@@ -774,6 +774,12 @@ export async function handleQuickStageCompletion({ stageName, steps, currentIdx,
         changedFiles: realFiles,
       })
       console.log(`📝 QUICKLOG 条目 ${qlId} 已标记完成`)
+      // 刷新 DB title：从 step3「需求：」提取（agent 可改 title 的途径），覆盖启动时的兜底快照。
+      // 与 QUICKLOG 标题刷新（flipEntryInContent 内 extractTitleFromResult）同源，保持 DB↔QUICKLOG 一致。
+      try {
+        const refinedTitle = extractTitleFromResult(outputText || '');
+        if (refinedTitle) pm.updateChangeMeta(cwd, changeName, { title: refinedTitle });
+      } catch { /* title 刷新失败不阻断完成 */ }
     } catch (e) {
       console.warn(`⚠️ QUICKLOG 完成态写入失败: ${e.message}`)
     }

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 })