sillyspec 3.26.8 → 3.26.9

package/src/constants.js

@@ -1,106 +1,97 @@
-/**
- * SillySpec 平台状态枚举
- *
- * 所有平台产物（manifest、pointer、postcheck、workflow-runs）共享这些枚举。
- * SillyHub 侧直接使用常量值，不需要猜字符串。
- */
-
-// ── scan 阶段状态 ──
-export const SCAN_STATUS = Object.freeze({
-  PENDING: 'pending',                        // scan 未开始
-  IN_PROGRESS: 'in_progress',                  // scan 进行中
-  SUCCESS: 'success',                          // scan 成功（所有检查通过）
-  COMPLETED_WITH_WARNINGS: 'completed_with_warnings',  // scan 成功但有警告
-  FAILED_POST_CHECK: 'failed_post_check',     // scan 失败（post-check 不通过）
-})
-
-// ── 平台指针状态 ──
-export const POINTER_STATUS = Object.freeze({
-  ACTIVE: 'active',                            // 指针活跃，任务进行中
-  SCAN_COMPLETED: 'scan_completed',             // scan 已完成
-  STALE: 'stale',                              // 指针过时（完成超过 24h，建议清理）
-  CORRUPTED: 'corrupted',                      // 指针损坏（缺少必要字段）
-})
-
-// ── workflow 检查状态 ──
-export const WORKFLOW_STATUS = Object.freeze({
-  PASS: 'pass',
-  FAIL: 'fail',
-  SKIPPED: 'skipped',
-})
-
-// ── postcheck 检查严重级别 ──
-export const CHECK_SEVERITY = Object.freeze({
-  FAILED: 'failed',
-  WARNING: 'warning',
-  PASSED: 'passed',
-})
-
-// ── stage 步骤状态 ──
-export const STEP_STATUS = Object.freeze({
-  PENDING: 'pending',
-  IN_PROGRESS: 'in-progress',
-  COMPLETED: 'completed',
-  SKIPPED: 'skipped',
-})
-
-// ── stage 阶段状态 ──
-export const STAGE_STATUS = Object.freeze({
-  PENDING: 'pending',
-  IN_PROGRESS: 'in_progress',
-  COMPLETED: 'completed',
-  FAILED_POST_CHECK: 'failed_post_check',
-})
-
-/**
- * 判断指针是否过时（完成超过 24h）
- */
-export function isPointerStale(pointer) {
-  if (!pointer.completedAt) return false
-  const completed = new Date(pointer.completedAt)
-  const age = Date.now() - completed.getTime()
-  return age > 24 * 60 * 60 * 1000
-}
-
-/**
- * 判断指针是否损坏（缺少必要字段）
- */
-export function isPointerCorrupted(pointer) {
-  return !pointer || !pointer.specRoot || !pointer.savedAt
-}
-
-// ── scan 必需文档清单（stage-contract validator 与 scan-postcheck 共用单一真相源）──
-// 曾分两处硬编码同一份清单，加新文档需同步改两处，易分叉。现收敛到此处一处。
-export const SCAN_REQUIRED_DOCS = Object.freeze([
-  'ARCHITECTURE.md',
-  'CONVENTIONS.md',
-  'STRUCTURE.md',
-  'INTEGRATIONS.md',
-  'TESTING.md',
-  'CONCERNS.md',
-  'PROJECT.md',
-])
-
-// ── scan quick profile 必需文档子集（4 份核心文档）──
-// quick 档（--quick 显式 或 小项目自动判定）只生成这 4 份；scan-postcheck 按 profile 取清单：
-// mode==='quick' → SCAN_REQUIRED_DOCS_QUICK，否则 → SCAN_REQUIRED_DOCS（7 份）。
-// 由 scan-postcheck.js + complete-handlers.js 透传的 scanProfile.mode 决定取哪份。
-export const SCAN_REQUIRED_DOCS_QUICK = Object.freeze([
-  'PROJECT.md',
-  'ARCHITECTURE.md',
-  'CONVENTIONS.md',
-  'STRUCTURE.md',
-])
-
-// ── 辅助 stage 清单（stage-contract 转移规则 与 stages/index 注册表 共用单一真相源）──
-// 曾在 stage-contract.js 与 stages/index.js 逐字重复定义，新增/调整辅助 stage 需同步改两处
-// 易分叉。现收敛一处。（注意：主流程序 STAGE_ORDER/mainFlowStages/flowStages 语义不同、
-// 各自用途正确，不在本清单范围。）
-export const AUXILIARY_STAGES = Object.freeze([
-  'scan',
-  'quick',
-  'explore',
-  'archive',
-  'status',
-  'doctor',
-])
+/**
+ * SillySpec 平台状态枚举
+ *
+ * 所有平台产物（manifest、pointer、postcheck、workflow-runs）共享这些枚举。
+ * SillyHub 侧直接使用常量值，不需要猜字符串。
+ */
+
+// ── scan 阶段状态 ──
+export const SCAN_STATUS = Object.freeze({
+  PENDING: 'pending',                        // scan 未开始
+  IN_PROGRESS: 'in_progress',                  // scan 进行中
+  SUCCESS: 'success',                          // scan 成功（所有检查通过）
+  COMPLETED_WITH_WARNINGS: 'completed_with_warnings',  // scan 成功但有警告
+  FAILED_POST_CHECK: 'failed_post_check',     // scan 失败（post-check 不通过）
+})
+
+// ── 平台指针状态 ──
+export const POINTER_STATUS = Object.freeze({
+  ACTIVE: 'active',                            // 指针活跃，任务进行中
+  SCAN_COMPLETED: 'scan_completed',             // scan 已完成
+  STALE: 'stale',                              // 指针过时（完成超过 24h，建议清理）
+  CORRUPTED: 'corrupted',                      // 指针损坏（缺少必要字段）
+})
+
+// ── workflow 检查状态 ──
+export const WORKFLOW_STATUS = Object.freeze({
+  PASS: 'pass',
+  FAIL: 'fail',
+  SKIPPED: 'skipped',
+})
+
+// ── postcheck 检查严重级别 ──
+export const CHECK_SEVERITY = Object.freeze({
+  FAILED: 'failed',
+  WARNING: 'warning',
+  PASSED: 'passed',
+})
+
+/**
+ * 判断指针是否过时（完成超过 24h）
+ */
+export function isPointerStale(pointer) {
+  if (!pointer.completedAt) return false
+  const completed = new Date(pointer.completedAt)
+  const age = Date.now() - completed.getTime()
+  return age > 24 * 60 * 60 * 1000
+}
+
+/**
+ * 判断指针是否损坏（缺少必要字段）
+ */
+export function isPointerCorrupted(pointer) {
+  return !pointer || !pointer.specRoot || !pointer.savedAt
+}
+
+// ── scan 必需文档清单（stage-contract validator 与 scan-postcheck 共用单一真相源）──
+// 曾分两处硬编码同一份清单，加新文档需同步改两处，易分叉。现收敛到此处一处。
+export const SCAN_REQUIRED_DOCS = Object.freeze([
+  'ARCHITECTURE.md',
+  'CONVENTIONS.md',
+  'STRUCTURE.md',
+  'INTEGRATIONS.md',
+  'TESTING.md',
+  'CONCERNS.md',
+  'PROJECT.md',
+])
+
+// ── scan quick profile 必需文档子集（4 份核心文档）──
+// quick 档（--quick 显式 或 小项目自动判定）只生成这 4 份；scan-postcheck 按 profile 取清单：
+// mode==='quick' → SCAN_REQUIRED_DOCS_QUICK，否则 → SCAN_REQUIRED_DOCS（7 份）。
+// 由 scan-postcheck.js + complete-handlers.js 透传的 scanProfile.mode 决定取哪份。
+export const SCAN_REQUIRED_DOCS_QUICK = Object.freeze([
+  'PROJECT.md',
+  'ARCHITECTURE.md',
+  'CONVENTIONS.md',
+  'STRUCTURE.md',
+])
+
+// ── 辅助 stage 清单（stage-contract 转移规则 与 stages/index 注册表 共用单一真相源）──
+// 曾在 stage-contract.js 与 stages/index.js 逐字重复定义，新增/调整辅助 stage 需同步改两处
+// 易分叉。现收敛一处。（注意：主流程序 STAGE_ORDER/mainFlowStages/flowStages 语义不同、
+// 各自用途正确，不在本清单范围。）
+export const AUXILIARY_STAGES = Object.freeze([
+  'scan',
+  'quick',
+  'explore',
+  'archive',
+  'status',
+  'doctor',
+])
+
+// ── 只读辅助 stage 清单（查询型辅助阶段，可读短路不触碰进度库）──
+// 供 command.js 判断 status/doctor 等查询型辅助阶段执行只读短路（FR-04 / D-005@v2）。
+export const READONLY_AUXILIARY_STAGES = Object.freeze([
+  'status',
+  'doctor',
+])

package/src/db-engine.js

@@ -2,7 +2,7 @@
 // 封装 node:sqlite 内置模块 + 消解 better-sqlite3 → node:sqlite 三缺口：
 //   pragma → exec / transaction → 手写 SAVEPOINT / pluck → Object.values 取首列
 // 供 db.js 与 doctor-diagnostics 共用（方案 B 单一换引擎点，D-002）。
-// node:sqlite 在 node v22.11.0+ 无需 --experimental-sqlite flag（仍发 ExperimentalWarning）。
+// node:sqlite 在 node v22.13.0+ 无需 --experimental-sqlite flag（仍发 ExperimentalWarning）。
 // Author: sillyspec execute W1 task-02
 // Created: 2026-08-11
 import { DatabaseSync } from 'node:sqlite';

package/src/docs-check.js

@@ -12,12 +12,15 @@
  * 只读校验（不修改任何被校验文件）；纯 Node 内置模块零依赖（D-008：glob 手写 walker，
  * 仅「目录递归」「目录单层」「字面路径」三形态）；Windows 路径归一化；兼容 CRLF/LF。
  */
-import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import jsYaml from 'js-yaml'
 
 /** 提取 file.js:line / file.js:start-end 引用（.js/.mjs，反引号包裹与裸文本均命中，全文扫描 D-006） */
-export const REF_RE = /([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
+const REF_RE = /([A-Za-z0-9_.\-\/]+\.(?:js|mjs)):(\d+)(?:-(\d+))?/g
+
+/** 缺省扫描范围：docs/ + .sillyspec/docs/（scan/modules 产物同是文档，失效即该暴露；2026-08-16 用户裁决改缺省，见 doc-consistency-debt.md §八） */
+const DEFAULT_DOC_PATHS = ['docs/**/*.md', '.sillyspec/docs/**/*.md']
 
 /**
  * 读 local.yaml 的 docs-check 段（best-effort，绝不抛；缺文件/无段 → 全缺省）。
@@ -187,6 +190,26 @@ export function walkGlob(projectRoot, pattern, skip = []) {
       (sn.includes('*') && matchSimple(rel, sn))
   })
   const matchExt = (name, ext) => name.endsWith(ext)
+  // 形态 0：**/*.ext（根级递归，无 base 前缀——B11b：原被形态 2 误解析为字面目录 `**` 静默 0 命中）
+  let m0 = norm(pattern).match(/^\*\*\/\*(\.[A-Za-z0-9]+)$/)
+  if (m0) {
+    const [, ext] = m0
+    const out = []
+    const rec = (dir, rel, depth) => {
+      if (depth > 12) return
+      let entries
+      try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+      for (const e of entries) {
+        if (e.name === 'node_modules' || e.name === '.git') continue
+        const relPath = rel ? `${rel}/${e.name}` : e.name
+        if (isSkipped(relPath)) continue
+        if (e.isDirectory()) rec(join(dir, e.name), relPath, depth + 1)
+        else if (matchExt(e.name, ext)) out.push(relPath)
+      }
+    }
+    rec(projectRoot, '', 0)
+    return out
+  }
   // 形态 1：**/*.ext
   let m = norm(pattern).match(/^(.+?)\/\*\*\/\*(\.[A-Za-z0-9]+)$/)
   if (m) {
@@ -224,7 +247,13 @@ export function walkGlob(projectRoot, pattern, skip = []) {
   }
   // 形态 3：字面路径（不含任何通配元字符才直传；含 ?、{ }、[ ] 等不支持形态落 error）
   if (!/[*?{}\[\]]/.test(pattern)) {
-    return existsSync(join(projectRoot, pattern)) ? [norm(pattern)] : []
+    const abs = join(projectRoot, pattern)
+    if (!existsSync(abs)) return []
+    // B11b：目录字面量抛配置错误（原直传 readFileSync 撞 EISDIR 裸崩 exit 1；契约应 exit 2）
+    if (statSync(abs).isDirectory()) {
+      throw new DocsCheckConfigError(`路径是目录不是文档：${pattern}（文档路径应为 .md 文件或 glob 形态 **/*.ext / dir/**/*.ext / dir/*.ext）`)
+    }
+    return [norm(pattern)]
   }
   throw new DocsCheckConfigError(`不支持的 glob 形态：${pattern}（当前仅支持 dir/**/*.ext、dir/*.ext、字面路径）`)
 }
@@ -247,8 +276,8 @@ function relDisplay(absPath, projectRoot) {
 export function runDocsCheck(opts) {
   // paths/docs 显式传 null（readDocsCheckConfig 无 local.yaml 段时的回退值）须落回缺省 glob，
   // 解构默认值只挡 undefined 不挡 null——docs-check 无配置裸跑曾因此 null.flatMap 崩溃。
-  const { projectRoot, docs = null, paths: rawPaths = ['docs/**/*.md'], skip = [], keywordAssert = true } = opts || {}
-  const paths = Array.isArray(rawPaths) && rawPaths.length > 0 ? rawPaths : ['docs/**/*.md']
+  const { projectRoot, docs = null, paths: rawPaths = DEFAULT_DOC_PATHS, skip = [], keywordAssert = true } = opts || {}
+  const paths = Array.isArray(rawPaths) && rawPaths.length > 0 ? rawPaths : DEFAULT_DOC_PATHS
   const warnings = []
   if (keywordAssert === false) warnings.push('关键词断言已关闭（keywordAssert=false），仅做存在性校验')
   const docFiles = docs && docs.length > 0

package/src/git-helper.js

@@ -34,7 +34,7 @@ export function safeGit(cwd, args, opts = {}) {
   // 格式化（取首行）推迟到最终返回，避免重试分支重复格式化，并保留原始 code 供重试判定。
   const attempt = (t) => {
     try {
-      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t })
+      let value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout: t, stdio: ['ignore', 'pipe', 'pipe'] })
       if (trim) value = value.trim()
       return { value, errorObj: null }
     } catch (e) {
@@ -59,7 +59,7 @@ export function safeGit(cwd, args, opts = {}) {
 export function git(cwd, args, opts = {}) {
   const { trim = true, timeout = 5000 } = opts
   const fullArgs = ['-c', `safe.directory=${cwd}`, '-C', cwd, ...args]
-  const value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout })
+  const value = execFileSync('git', fullArgs, { encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] })
   return trim ? value.trim() : value
 }
 

package/src/hooks/worktree-guard.js

@@ -748,7 +748,7 @@ export function shouldBlockWrite(filePath, cwd) {
  * @param {string} cwd - 当前工作目录
  * @returns {{ blocked: boolean, reason?: string }}
  */
-export function shouldBlockBash(command, cwd) {
+function shouldBlockBash(command, cwd) {
   if (!command || !command.trim()) return { blocked: false }
 
   const callerCwd = cwd || process.cwd()

package/src/index.js

@@ -8,16 +8,19 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { writeAtomicSync } from './fs-atomic.js';
-import { join, resolve } from 'path';
+import { basename, join, resolve } from 'path';
 import { execSync } from 'child_process';
 import { git } from './git-helper.js';
 import { getVersion } from './version.js';
-import { ProgressManager, resolvePlatformSpecDir } from './progress.js';
+
+// E22（性能#2）：progress.js（拖 db.js→node:sqlite 链 ~48ms）与 run/shared.js（拖 stages 全家
+// ~30ms）原先为顶层静态 import——最轻命令（--version/help）白付 ~78ms 启动税。两条链无模块级
+// 使用点（printUsage 纯文本），改在 main() 早退之后动态加载，轻路径零加载；重路径首个使用点
+// 之前完成加载，行为零变化。
 
 // ── CLI 入口 ──
 
-// did-you-mean 从 ./run/shared.js 复用（命令级 + flag 级 typo 建议）。
-import { didYouMean, assertSafeChangeName, resolveSpecDir, detectWorktreeSpecDrift } from './run/shared.js'
+// did-you-mean 从 ./run/shared.js 复用（命令级 + flag 级 typo 建议）。E22：同上改惰性动态加载。
 function printUsage() {
   console.log(`
 SillySpec CLI — 规范驱动开发工具包
@@ -56,6 +59,8 @@ SillySpec CLI — 规范驱动开发工具包
              --confirm                   完成时确认接受变更审计
     scan:    --quick | --standard | --deep   显式选择 profile（优先于规模自动判定；三档互斥）
              --force-rescan              覆盖已有 scan 文档保护
+             --diff [--base <commit>] [--full] [--report]   scan 文档 vs 源码漂移清单（纯只读）
+             （子命令: sillyspec scan diff 等价 --diff）
     archive: --confirm                   归档确认（必须）
     auto:    --mode <模式>               显式指定流程模式
     平台:    --runtime-root <path> / --workspace-id <id> / --scan-run-id <id>
@@ -159,6 +164,10 @@ async function main() {
     process.exit(0);
   }
 
+  // E22：重路径统一加载（轻路径 --version/help 已早退，未付此税）。
+  const { ProgressManager, resolvePlatformSpecDir } = await import('./progress.js');
+  const { didYouMean, assertSafeChangeName, resolveSpecDir, detectWorktreeSpecDrift } = await import('./run/shared.js');
+
   // 解析全局选项
   let json = false;
   let saveWorkflowRunFlag = false;
@@ -308,21 +317,21 @@ async function main() {
           break;
         case 'set-stage': {
           const setStageName = filteredArgs[2];
-          if (!setStageName) { console.log('❌ 用法: sillyspec progress set-stage <stage> [--change <name>]'); break; }
+          if (!setStageName) { console.log('❌ 用法: sillyspec progress set-stage <stage> [--change <name>]'); process.exit(2); }
           pm.setStage(dir, setStageName, progChangeName);
           break;
         }
         case 'add-step': {
           const addStepStage = filteredArgs[2];
           const addStepName = filteredArgs[3];
-          if (!addStepStage || !addStepName) { console.log('❌ 用法: sillyspec progress add-step <stage> <step-name> [--change <name>]'); break; }
+          if (!addStepStage || !addStepName) { console.log('❌ 用法: sillyspec progress add-step <stage> <step-name> [--change <name>]'); process.exit(2); }
           pm.addStep(dir, addStepStage, addStepName, progChangeName);
           break;
         }
         case 'update-step': {
           const updStepStage = filteredArgs[2];
           const updStepName = filteredArgs[3];
-          if (!updStepStage || !updStepName) { console.log('❌ 用法: sillyspec progress update-step <stage> <step-name> --status <status> [--output <text>] [--change <name>]'); break; }
+          if (!updStepStage || !updStepName) { console.log('❌ 用法: sillyspec progress update-step <stage> <step-name> --status <status> [--output <text>] [--change <name>]'); process.exit(2); }
           let updStatus = null, updOutput = undefined;
           for (let ai = 0; ai < args.length; ai++) {
             if (args[ai] === '--status' && args[ai + 1]) { updStatus = args[ai + 1]; ai++; }
@@ -334,7 +343,7 @@ async function main() {
         }
         case 'complete-stage': {
           const compStageName = filteredArgs[2];
-          if (!compStageName) { console.log('❌ 用法: sillyspec progress complete-stage <stage> [--force]'); break; }
+          if (!compStageName) { console.log('❌ 用法: sillyspec progress complete-stage <stage> [--force]'); process.exit(2); }
           pm.completeStage(dir, compStageName, progChangeName, { force: args.includes('--force') });
           break;
         }
@@ -357,7 +366,7 @@ async function main() {
             if (Object.keys(batchData).length === 0) {
               console.log('用法: sillyspec progress batch --total 100 --completed 73');
               console.log('     sillyspec progress batch --status');
-              break;
+              process.exit(2);
             }
             pm.updateBatchProgress(dir, batchData, progChangeName);
             console.log('✅ 批量进度已更新');
@@ -366,6 +375,7 @@ async function main() {
         }
         default:
           console.log('用法: sillyspec progress <init|show|validate|reset|set-stage|add-step|update-step|complete-stage>');
+          process.exit(2);
       }
       break;
     }
@@ -387,7 +397,11 @@ async function main() {
       // 只传 cwd 致 --spec-dir 对 gate verify 无效。不传 --spec-dir 时 specBase 走默认
       // resolveSpecDir(cwd)，向后兼容。
       const gateOpts = { cwd: dir };
-      if (specDir) gateOpts.specBase = specDir;
+      // A4：平台指针 / 显式 --spec-dir / 本地 fallback 三合一解析 specBase——平台模式（指针指向外部
+      // specDir）下 gate 也能核验（原只传 cwd 致 runGate 的 resolveSpecDir 指向本地孤儿库，恒
+      // 「无法核验」exit 2）。resolvePlatformSpecDir 指针失效时抛 PointerUnreachableError，由顶层 catch 优雅 fail-closed。
+      const gateSpecBase = resolvePlatformSpecDir(dir, specDir);
+      if (gateSpecBase) gateOpts.specBase = gateSpecBase;
       // drift 锚定（坑 execute-runs-isolation，对齐 command.js execute drift 守卫 + machine-interface
       // runGate 已扩展的 specDriftAnchor 入参）：gate 是顶层命令不走 runCommand/drift 守卫，worktree cwd
       // 下 execute 段 marker 读取会落副本 .runtime。仅在未显式 --spec-dir 时算（对齐守卫条件 !specDir），
@@ -442,7 +456,9 @@ async function main() {
       // derive verify-test facet 内部同样调 runVerifyTestCheck 依赖 specBase，平台模式
       // 下需透传；不传 --spec-dir 时走默认 resolveSpecDir(cwd)，向后兼容。
       const deriveOpts = { cwd: dir };
-      if (specDir) deriveOpts.specBase = specDir;
+      // A4：同 gate case——平台指针/--spec-dir/本地 fallback 三合一解析 specBase。
+      const deriveSpecBase = resolvePlatformSpecDir(dir, specDir);
+      if (deriveSpecBase) deriveOpts.specBase = deriveSpecBase;
       // drift 锚定（同 gate case，对齐 command.js drift 守卫 + machine-interface runDerive 的 specDriftAnchor
       // 入参）：derive 顶层命令不走 drift 守卫，worktree cwd 下 task-reviews facet 的 execute-run-id marker
       // 读取会落副本。未显式 --spec-dir 时算 anchor，runDerive task-reviews 的 resolveRuntimeRoot 读主仓 marker。
@@ -629,8 +645,54 @@ async function main() {
           }
           throw e;
         }
+      } else if (docsSubCmd === 'gate') {
+        // docs gate ratchet（docs-signals-o12 cff7479 产品化，pre-push 第三道关）：docs check
+        // 失效数 ≤ 基线放行，超基线拦。基线 .sillyspec/docs-check-baseline 首次须显式
+        // --init-baseline 立线（fail-closed，不悄悄合法化存量）。
+        // ⚠ 2026-08-16 补接线：cff7479 落地时漏了本 CLI 分支，.husky/pre-push 一直在跑
+        // usage 输出且 exit 0——gate 形同虚设（docs-signals 范围内文件+hook 已就位，仅此分支缺）。
+        // B9（2026-08-16）：flag 白名单化（对齐 docs check 分支）——未知 --xxx 显式 exit 2
+        // （interface-contract §1.3b 宣称），并接线 --paths 透传 runDocsGate.checkOpts（原被忽略）。
+        const GATE_BARE_FLAGS = ['--init-baseline'];
+        const GATE_PAIRED_FLAGS = ['--paths'];
+        const rawGateArgs = filteredArgs.slice(2);
+        let initBaseline = false;
+        let cliGatePaths = null;
+        for (let i = 0; i < rawGateArgs.length; i++) {
+          const a = rawGateArgs[i];
+          if (a === '--paths' && rawGateArgs[i + 1] !== undefined) {
+            cliGatePaths = rawGateArgs[i + 1].split(',').map(s => s.trim()).filter(Boolean);
+            i++;
+          } else if (a === '--paths') {
+            console.error('❌ docs gate: --paths 缺值（逗号分隔 glob，如 --paths "docs/**/*.md"）');
+            process.exit(2);
+          } else if (GATE_BARE_FLAGS.includes(a)) {
+            if (a === '--init-baseline') initBaseline = true;
+          } else if (a.startsWith('--')) {
+            console.error(`❌ docs gate: 未知 flag「${a}」。已知 flag：${[...GATE_BARE_FLAGS, ...GATE_PAIRED_FLAGS].join(' ')}（--json 为全局 flag）`);
+            process.exit(2);
+          } else {
+            console.error(`❌ docs gate: 多余位置参数「${a}」。用法：sillyspec docs gate [--init-baseline] [--paths <glob,...>] [--json]`);
+            process.exit(2);
+          }
+        }
+        const { runDocsGate } = await import('./docs-gate.js');
+        // specBase：平台模式（specDir 指针）优先，本地回退 <repo>/.sillyspec——基线文件锚定
+        // 进度库根（与 .runtime 同级），跨命令稳定。
+        const gateSpecBase = specDir || join(dir, '.sillyspec');
+        const g = await runDocsGate(
+          { projectRoot: dir, specBase: gateSpecBase, initBaseline },
+          cliGatePaths ? { paths: cliGatePaths } : undefined
+        );
+        if (json) {
+          console.log(JSON.stringify(g, null, 2));
+        } else {
+          console.log(g.message);
+        }
+        process.exit(g.exitCode);
       } else {
-        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] [--suggest]');
+        console.log('用法: sillyspec docs migrate | sillyspec docs check [--paths <glob,...>] [--json] [--suggest] | sillyspec docs gate [--init-baseline] [--json]');
+        process.exit(2);
       }
       break;
     }
@@ -766,7 +828,27 @@ async function main() {
       await runCommand([command, ...filteredArgs.slice(1)], doctorEffectiveDir, specDir, { json });
       break;
     }
-    case 'scan':
+    case 'scan': {
+      // scan diff 子命令（D-001@v1：接线唯一入口 index.js，非 command.js 裸 token 静默吞）。
+      // 纯只读比较命令：跳过下方共享块的 triggerPullActiveChange（不触发网络 pull），
+      // 也不走 scan 主流程（--standard/--deep 分支不动）。解析 --base/--full/--report 后转发 scan-diff。
+      if (filteredArgs[1] === 'diff') {
+        const { runScanDiff } = await import('./scan-diff.js')
+        const diffBaseIdx = filteredArgs.indexOf('--base')
+        const diffBase = diffBaseIdx >= 0 && filteredArgs[diffBaseIdx + 1] ? filteredArgs[diffBaseIdx + 1] : null
+        // specBase/projectName 与 scan 主流程同口径（scan-profile.js：specBase=进度库根，projectName=仓库根 basename）
+        const diffEffectiveDir = specDir ? dir : resolveEffectiveDir(dir)
+        process.exitCode = runScanDiff({
+          projectRoot: diffEffectiveDir,
+          specBase: specDir || join(diffEffectiveDir, '.sillyspec'),
+          projectName: basename(diffEffectiveDir),
+          base: diffBase,
+          full: filteredArgs.includes('--full'),
+          report: filteredArgs.includes('--report'),
+        })
+        break
+      }
+    }
     case 'status':
     case 'quick':
     case 'explore':
@@ -774,6 +856,7 @@ async function main() {
     case 'plan':
     case 'execute':
     case 'verify':
+    case 'auto':
     case 'archive': {
       const { runCommand } = await import('./run.js')
       const stageArgs = [command, ...filteredArgs.slice(1)]

package/src/init.js

@@ -470,6 +470,14 @@ export async function cmdInit(projectDir, options = {}) {
   const version = getVersion();
   const resolvedSpecDir = specDir ? resolve(specDir) : null;
 
+  // C14c：绿地/棕地引导——必须在 doInstall 之前捕获目录状态（init 会创建 .sillyspec/CLAUDE.md/
+  // .gitignore 等，事后检测会误判）；棕地（已有非隐藏源码）建议 scan，绿地（空目录）建议 brainstorm。
+  let brownfield = false;
+  try {
+    const entries = readdirSync(projectDir, { withFileTypes: true });
+    brownfield = entries.some(e => !e.name.startsWith('.'));
+  } catch { brownfield = false; }
+
   // ── 交互式模式（--interactive 或 -i）──
   if (interactive && isTTY()) {
     // 欢迎画面
@@ -603,9 +611,12 @@ export async function cmdInit(projectDir, options = {}) {
   const specDisplay = resolvedSpecDir || '.sillyspec';
   console.log(`  📁 规范目录: ${chalk.cyan(specDisplay)}`);
   console.log('');
-  console.log('  下一步：使用 AI 技能开始工作');
-  console.log(`    OpenClaw:    ${chalk.bold('/sillyspec:brainstorm')}`);
-  console.log(`    Claude Code: ${chalk.bold('/sillyspec:brainstorm')}`);
+  // C14c：绿地/棕地引导区分（README:73 棕地应 scan）——early 捕获的目录状态（init 前），
+  // 棕地有代码零上下文进 brainstorm 会迷失，建议先 scan 生成架构文档。
+  const nextCmd = brownfield ? '/sillyspec:scan' : '/sillyspec:brainstorm';
+  console.log('  下一步：使用 AI 技能开始工作' + (brownfield ? '（检测到现有代码，建议先扫描生成架构文档）' : ''));
+  console.log(`    OpenClaw:    ${chalk.bold(nextCmd)}`);
+  console.log(`    Claude Code: ${chalk.bold(nextCmd)}`);
   console.log('');
   console.log(chalk.dim('  💡 增强能力：sillyspec setup（安装 MCP 工具）'));
   console.log('');

package/src/machine-interface.js

@@ -113,14 +113,16 @@ export function buildEnvelope({
  */
 export async function runGate(stage, changeName, { cwd, specBase, runtimeRoot, specDriftAnchor, ctx = null } = {}) {
   const specRoot = specBase || resolveSpecDir(cwd);
-  const pm = new ProgressManager();
+  // A4：pm 用 specRoot（而非默认 resolveSpecDir(cwd)）——--spec-dir/平台模式下 specBase 是真实
+  // specDir，默认解析会指向本地孤儿库，与下方 planContent/changeDir 的 specRoot 两套事实源混拼。
+  const pm = new ProgressManager({ specDir: specRoot });
 
   try {
     // ── 只读契约守卫（D-002@v1）：db 不存在时 fail-closed 返回 exit 2，不触发建库落盘 ──
     // pm.read → _ensureDB → db.init() 在 db 不存在/schema 戳落后时会 _createSchema + _save 落盘
     // （db.js:init），这会让一个声明只读的查询命令在 spec 目录凭空建 sillyspec.db，违反只读契约。
     // db 还没建 = 该变更从未跑过流程，无从核验 → 显式返回「无法核验」而非建库。
-    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
     if (!existsSync(dbPath)) {
       const envelope = buildEnvelope({
         command: 'gate',
@@ -356,11 +358,12 @@ export async function runDerive(facet, changeName, { cwd, specBase, runtimeRoot,
   }
 
   const specRoot = specBase || resolveSpecDir(cwd);
-  const pm = new ProgressManager();
+  // A4：同 runGate——pm 用 specRoot 统一事实源，平台/--spec-dir 模式不读本地孤儿库。
+  const pm = new ProgressManager({ specDir: specRoot });
 
   try {
     // ── 只读契约守卫（D-002@v1，同 runGate）：db 不存在时 fail-closed 返回 exit 2，不建库落盘 ──
-    const dbPath = join(resolveSpecDir(cwd), '.runtime', 'sillyspec.db');
+    const dbPath = join(specRoot, '.runtime', 'sillyspec.db');
     if (!existsSync(dbPath)) {
       const envelope = buildEnvelope({
         command: 'derive',

package/src/progress/stage-machine.js

@@ -275,7 +275,10 @@ export class StageMachine {
     }
 
     // 找到第一个有 pending/waiting/failed 步骤的 in-progress 阶段
+    // C14b：排除 scan（同下方主流程推荐循环）——scan 是 auxiliary，中途未完成时恒处
+    // STAGE_ORDER 首位且 in-progress，会把「下一步」劫持为 scan，掩盖主流程真实待办。
     for (const s of STAGE_ORDER) {
+      if (s === 'scan') continue
       const sd = data.stages[s];
       if (!sd) continue;
       if (sd.status === 'in-progress' && sd.steps) {