sillyspec 3.17.15 → 3.18.1

package/docs/platform-scan-protocol.md

@@ -0,0 +1,298 @@
+# 平台 Scan 产物协议
+
+SillySpec 平台执行模式的核心设计：**SillySpec 写产物，SillyHub 读产物**。平台不看 stdout，只靠文件系统判断 scan 成功、失败原因和证据文件位置。
+
+## 状态枚举（src/constants.js）
+
+所有平台产物共享同一套枚举值，SillyHub 直接使用常量，不猜字符串。
+
+### SCAN_STATUS
+
+| 值 | 说明 |
+---|---|
+| `pending` | scan 未开始 |
+| `in_progress` | scan 进行中 |
+| `success` | scan 成功，所有检查通过 |
+| `completed_with_warnings` | scan 成功但有警告 |
+| `failed_post_check` | scan 失败，post-check 不通过 |
+
+### POINTER_STATUS
+
+| 值 | 说明 |
+---|---|
+| `active` | 指针活跃，任务进行中 |
+| `scan_completed` | scan 已完成 |
+| `stale` | 指针过时（完成超过 24h，建议清理） |
+| `corrupted` | 指针损坏（缺少必要字段） |
+
+### CHECK_SEVERITY
+
+| 值 | 说明 |
+---|---|
+| `failed` | 严重：阻止成功 |
+| `warning` | 警告：不阻止成功 |
+| `passed` | 通过 |
+
+## 目录结构
+
+```
+<spec_root>/
+├── manifest.json                          # 扫描元数据 + 产物索引
+├── docs/<project>/scan/                    # 项目文档
+│   ├── ARCHITECTURE.md
+│   ├── CONVENTIONS.md
+│   ├── PROJECT.md
+│   ├── STACK.md
+│   ├── STRUCTURE.md
+│   └── ... (7 份必需文档)
+├── projects/*.yaml                         # 子项目注册
+├── changes/<change-name>/                  # 变更目录
+└── .runtime/
+    ├── postcheck-result.json              # post-check 结构化结果
+    └── platform-scan.json                  # 平台参数持久化（主文件）
+
+<runtime_root>/
+└── scan-runs/<scan_run_id>/
+    └── workflow-runs/
+        └── <timestamp>-<workflow>-<project>-<status>.json  # workflow 检查结果
+
+<source_root>/
+├── .sillyspec-platform.json               # 平台参数恢复指针（轻量，不在 .sillyspec 内）
+└── (源码，禁止 .sillyspec/ 污染)
+```
+
+## manifest.json
+
+scan 完成后写入 `<spec_root>/manifest.json`，是 SillyHub 判断 scan 结果的入口文件。
+
+### 结构
+
+```json
+{
+  "workspace_id": "ws-xxx",
+  "scan_run_id": "scan-2026-06-14-test-001",
+  "source_root": "/path/to/source",
+  "spec_root": "/path/to/spec",
+  "runtime_root": "/path/to/runtime",
+  "source_commit": "abc123...",
+  "source_commit_error": null,
+  "generated_at": "2026-06-14T01:50:00.000Z",
+  "schema_version": 1,
+  "postcheck_result_path": "<spec_root>/.runtime/postcheck-result.json",
+  "workflow_runs_dir": "<runtime_root>/scan-runs/<scan_run_id>/workflow-runs",
+  "platform_pointer_path": "<source_root>/.sillyspec-platform.json",
+  "platform_pointer_status": "active",
+  "scan_post_check": {
+    "status": "success | completed_with_warnings | failed_post_check",
+    "checks": [...]
+  }
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `workspace_id` | string \| null | SillyHub workspace 标识 |
+| `scan_run_id` | string \| null | 本次 scan 唯一标识 |
+| `source_root` | string | 源码目录绝对路径 |
+| `spec_root` | string \| null | 规范目录（specDir） |
+| `runtime_root` | string \| null | 运行时产物目录 |
+| `source_commit` | string \| null | 源码 HEAD commit hash |
+| `source_commit_error` | string \| undefined | commit 获取失败原因 |
+| `generated_at` | string (ISO 8601) | manifest 生成时间 |
+| `schema_version` | number | 产物协议版本，当前为 1 |
+| `postcheck_result_path` | string \| null | post-check 结构化结果路径 |
+| `workflow_runs_dir` | string \| null | workflow 检查结果目录 |
+| `platform_pointer_path` | string | 平台指针文件路径 |
+| `platform_pointer_status` | string | 初始 `active`，由指针文件独立更新 |
+| `scan_post_check` | object \| undefined | post-check 结果（写入后追加） |
+
+### 判断 scan 结果
+
+SillyHub 消费 manifest 的方式：
+
+1. 读取 `<spec_root>/manifest.json`
+2. 检查 `scan_post_check.status`：
+   - `success` → scan 成功
+   - `completed_with_warnings` → scan 成功但有警告
+   - `failed_post_check` → scan 失败
+3. 如果失败，读 `scan_post_check.checks` 获取具体失败项
+4. 读 `postcheck_result_path` 获取完整结构化结果
+5. 读 `workflow_runs_dir` 获取 workflow 检查证据
+
+## .sillyspec-platform.json
+
+跨 `--done` 生命周期的轻量指针文件，存储在 `<source_root>/.sillyspec-platform.json`（不在 `.sillyspec/` 内，不污染源码结构）。
+
+### 生命周期
+
+| 阶段 | 行为 |
+|---|---|
+| **创建** | `run scan --spec-root` 时，写入 cwd 根目录 |
+| **读取** | 每次 `run`/`--done`/`--skip` 时，优先从 pointer 恢复平台参数 |
+| **更新** | 每次 `run` 时刷新 `savedAt` |
+| **完成标记** | scan post-check 后追加 `status=scan_completed` + `completedAt` + `scanStatus` |
+| **异常检测** | pointer 存在但缺 `specRoot` 时报错退出 |
+| **清理** | 无自动清理。`sillyspec platform pointer` 查看状态，`sillyspec platform pointer --cleanup` 手动清理 |
+
+### CLI 检查命令
+
+```bash
+# 查看指针状态
+sillyspec platform pointer
+
+# 清理过时/损坏指针
+sillyspec platform pointer --cleanup
+```
+
+输出示例：
+```
+📄 指针文件: /path/to/source/.sillyspec-platform.json
+   specRoot: /path/to/spec
+   runtimeRoot: /path/to/runtime
+   workspaceId: ws-xxx
+   scanRunId: scan-2026-06-14-test-001
+   savedAt: 2026-06-14T01:50:00.000Z
+   状态: stale ⚠️
+   completedAt: 2026-06-12T01:00:00.000Z
+   scanStatus: success
+   ⚠️ 指针已过时（完成超过 24h），可以安全删除。
+```
+
+状态判定逻辑：
+- 缺少 `specRoot` → `corrupted`
+- `status=scan_completed` 且 `completedAt` 超过 24h → `stale`
+- `status=scan_completed` 且未超时 → `scan_completed` ✅
+- 无 `status` 字段 → `active` 🔄
+
+### 结构
+
+```json
+{
+  "specRoot": "/path/to/spec",
+  "runtimeRoot": "/path/to/runtime",
+  "workspaceId": "ws-xxx",
+  "scanRunId": "scan-2026-06-14-test-001",
+  "savedAt": "2026-06-14T01:50:00.000Z"
+}
+```
+
+scan 完成后追加：
+
+```json
+{
+  "status": "scan_completed",
+  "completedAt": "2026-06-14T01:52:00.000Z",
+  "scanStatus": "success"
+}
+```
+
+## postcheck-result.json
+
+写入 `<spec_root>/.runtime/postcheck-result.json`（平台模式）或 `<cwd>/.sillyspec/.runtime/postcheck-result.json`（本地模式）。
+
+### 结构
+
+```json
+{
+  "workspace_id": "ws-xxx",
+  "scan_run_id": "scan-2026-06-14-test-001",
+  "status": "success | completed_with_warnings | failed_post_check",
+  "source_root": "/path/to/source",
+  "spec_root": "/path/to/spec",
+  "runtime_root": "/path/to/runtime",
+  "checks": [
+    {
+      "name": "source_root_docs_leak",
+      "severity": "failed | warning",
+      "detail": "..."
+    }
+  ],
+  "source_root_leak": true,
+  "docs_missing": ["ARCHITECTURE.md"],
+  "profile": {
+    "mode": "quick | standard | deep",
+    "file_count": 10,
+    "source_bytes": 102400,
+    "project_count": 1,
+    "reason": "..."
+  }
+}
+```
+
+### check 类型
+
+| check name | severity | 说明 |
+|---|---|---|
+| `source_root_docs_leak` | failed | docs 文档泄漏到 source_root |
+| `source_root_leak` | failed | projects/workflows/knowledge/manifest/local 泄漏到 source_root |
+| `all_docs_missing` | failed | 7 份必需文档全部缺失 |
+| `partial_docs_missing` | failed | 部分文档缺失 |
+| `docs_missing_header` | warning | 文档缺少 frontmatter |
+| `local_config_invalid` | warning | local.yaml 中命令不存在 |
+| `tool_use_error` | warning | AI 执行工具调用错误 |
+| `api_error` | warning | API 错误（529/429/超时） |
+
+## workflow-runs
+
+写入 `<runtime_root>/scan-runs/<scan_run_id>/workflow-runs/`（平台模式）或 `<cwd>/.sillyspec/.runtime/workflow-runs/`（本地模式）。
+
+每个文件命名：`<timestamp>-<workflow>-<project>-<status>.json`
+
+### 结构
+
+```json
+{
+  "run_id": "20260614015000-scan-docs-test-project-pass",
+  "created_at": "2026-06-14T01:50:00.000Z",
+  "source": "run.js",
+  "stage": "scan",
+  "step": "深度扫描",
+  "workflow": "scan-docs",
+  "project": "test-project",
+  "status": "pass | fail",
+  "spec_version": 1,
+  "roles": [...],
+  "workflow_checks": [...],
+  "failures": [...],
+  "retry_prompts": [...]
+}
+```
+
+## source_root 零污染
+
+平台模式的核心约束：source_root 下不产生 `.sillyspec/` 目录。
+
+post-check 会检查以下路径是否存在泄漏：
+- `<source_root>/.sillyspec/docs/` — 文档泄漏
+- `<source_root>/.sillyspec/projects/` — 项目注册泄漏
+- `<source_root>/.sillyspec/workflows/` — 工作流泄漏
+- `<source_root>/.sillyspec/knowledge/` — 术语泄漏
+- `<source_root>/.sillyspec/manifest.json` — manifest 泄漏
+- `<source_root>/.sillyspec/local.yaml` — 配置泄漏
+
+## 产物消费优先级
+
+SillyHub 判断 scan 结果的推荐顺序：
+
+1. `manifest.json` → `scan_post_check.overall_status` → 快速判断成功/失败
+2. `postcheck-result.json` → 完整检查明细 + failure_categories
+3. `workflow-runs/*.json` → workflow 检查证据
+4. `docs/<project>/scan/*.md` → 实际文档内容
+
+### failure_categories
+
+`postcheck-result.json` 中的 `failure_categories` 提供分类视图：
+
+| 类别 | 包含的 check |
+---|---|
+| `path_pollution` | source_root_leak, source_root_docs_leak |
+| `missing_outputs` | all_docs_missing, partial_docs_missing, missing_docs |
+| `bad_references` | local_config_invalid |
+| `quality_warnings` | tool_use_error, api_error_529, rate_limit_exhausted, fallback_or_skip |
+| `violations` | manifest_write_failed, project_list_parse_failed + 所有 path_pollution |
+
+SillyHub 可以按类别快速定位问题域，而不需要遍历所有 checks。
+
+不需要解析 stdout。

package/package.json

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

package/src/constants.js

@@ -0,0 +1,70 @@
+/**
+ * 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
+}

package/src/db.js

@@ -175,6 +175,10 @@ export class DB {
     this._migrateAddColumn('steps', 'wait_options', 'TEXT');
     this._migrateAddColumn('steps', 'wait_answer', 'TEXT');
     this._migrateAddColumn('steps', 'waited_at', 'TEXT');
+    // repeatableWait support
+    this._migrateAddColumn('steps', 'wait_answers', 'TEXT'); // JSON array
+    this._migrateAddColumn('steps', 'wait_round', 'INTEGER');
+    this._migrateAddColumn('steps', 'max_wait_rounds', 'INTEGER');
   }
 
   /**

package/src/hooks/worktree-guard.js

@@ -126,6 +126,96 @@ function isPathInside(child, parent) {
   return absChild === absParent || absChild.startsWith(absParent + path.sep)
 }
 
+function toPosixPath(filePath) {
+  return filePath.replace(/\\/g, '/')
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return {}
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/)
+  if (!match) return {}
+  const result = {}
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!m) continue
+    result[m[1]] = m[2].replace(/^['"]|['"]$/g, '').trim()
+  }
+  return result
+}
+
+function parseTimestamp(value) {
+  if (!value) return null
+  const time = Date.parse(value)
+  return Number.isNaN(time) ? null : time
+}
+
+function getScanDocInfo(filePath) {
+  const normalized = toPosixPath(path.resolve(filePath))
+  const match = normalized.match(/^(.*)\/docs\/([^/]+)\/scan\/([^/]+\.md)$/)
+  if (!match) return null
+  return {
+    specRoot: path.resolve(match[1]),
+    projectName: match[2],
+    docName: match[3],
+  }
+}
+
+function readScanGuard(scanDocInfo, projectRoot) {
+  const candidates = [
+    path.join(scanDocInfo.specRoot, '.runtime', 'scan-guard.json'),
+    path.join(projectRoot, '.sillyspec', '.runtime', 'scan-guard.json'),
+  ]
+  for (const p of candidates) {
+    if (!existsSync(p)) continue
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'))
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+function shouldBlockScanDocOverwrite(filePath, projectRoot) {
+  const scanDocInfo = getScanDocInfo(filePath)
+  if (!scanDocInfo || !existsSync(filePath)) return { blocked: false }
+
+  const guard = readScanGuard(scanDocInfo, projectRoot)
+  if (!guard || guard.forceRescan) return { blocked: false }
+
+  let frontmatter = {}
+  try {
+    frontmatter = parseFrontmatter(readFileSync(filePath, 'utf8'))
+  } catch {
+    return { blocked: false }
+  }
+
+  const relPath = toPosixPath(path.relative(projectRoot, filePath))
+  if (frontmatter.source_commit && guard.sourceCommit && frontmatter.source_commit !== guard.sourceCommit) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 source_commit=${frontmatter.source_commit} 与当前 scan source_commit=${guard.sourceCommit} 不一致。`,
+        '如确认要重新生成，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  const existingUpdatedAt = parseTimestamp(frontmatter.updated_at)
+  const scanStartedAt = parseTimestamp(guard.startedAt)
+  if (existingUpdatedAt && scanStartedAt && existingUpdatedAt > scanStartedAt) {
+    return {
+      blocked: true,
+      reason: [
+        `scan 覆盖保护：${relPath} 的 updated_at 晚于本次 scan 开始时间，可能包含手工编辑。`,
+        '如确认要覆盖，请重新运行 scan 并添加 --force-rescan。',
+      ].join('\n')
+    }
+  }
+
+  return { blocked: false }
+}
+
 function isInsideWorktreeStorage(filePath, cwd) {
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd || process.cwd(), filePath)
   return isPathInside(absPath, resolveWorktreeDir(cwd || process.cwd()))
@@ -489,12 +579,15 @@ export function shouldBlockWrite(filePath, cwd) {
   const projectRoot = findProjectRoot(callerCwd)
   const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(callerCwd, filePath)
 
-  // 1. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
-  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
-
-  // 2. 阶段门禁（使用 fallback 读取）
+  // 1. 阶段门禁（使用 fallback 读取）
   const stage = readCurrentStage(projectRoot) || '(none)'
 
+  const scanGuardResult = shouldBlockScanDocOverwrite(absPath, projectRoot)
+  if (scanGuardResult.blocked) return scanGuardResult
+
+  // 2. 文件门禁：文档类/配置类始终放行，但 worktree 存储区内的源码必须继续走登记校验。
+  if (!isInsideWorktreeStorage(absPath, projectRoot) && matchFileWhitelist(absPath)) return { blocked: false }
+
   if (!['execute', 'quick'].includes(stage)) {
     return {
       blocked: true,

package/src/index.js

@@ -40,7 +40,7 @@ SillySpec CLI — 规范驱动开发工具包
     auto                       连续推进 brainstorm→plan→execute→verify
 
   可选阶段:
-    scan, brainstorm, propose, plan, execute, verify, archive
+    scan, brainstorm, plan, execute, verify, archive
     quick, explore, status, doctor
 
   sillyspec progress <cmd>     进度记录（轻量，不强制顺序）
@@ -451,6 +451,7 @@ SillySpec platform — SillyHub 平台同步
   sillyspec platform sync [--change <name>]
   sillyspec platform sync-docs [--change <name>]
   sillyspec platform status
+  sillyspec platform pointer [--cleanup]
   sillyspec platform approve <change-name>
   sillyspec platform reject <change-name> [--reason <reason>]
 `);
@@ -466,6 +467,60 @@ SillySpec platform — SillyHub 平台同步
       }
 
       switch (platformSub) {
+        case 'pointer': {
+          // 指针状态检查（不依赖 sync 模块）
+          const { readFileSync, existsSync } = await import('fs')
+          const { join } = await import('path')
+          const { POINTER_STATUS, isPointerStale, isPointerCorrupted } = await import('./constants.js')
+          const pointerPath = join(dir, '.sillyspec-platform.json')
+
+          if (!existsSync(pointerPath)) {
+            console.log('ℹ️  无平台指针文件。当前不在平台模式或未进行过平台 scan。')
+            break
+          }
+
+          try {
+            const pointer = JSON.parse(readFileSync(pointerPath, 'utf8'))
+            console.log(`📄 指针文件: ${pointerPath}`)
+            console.log(`   specRoot: ${pointer.specRoot || '(缺失 ❌)'}`)
+            console.log(`   runtimeRoot: ${pointer.runtimeRoot || '(未设置)'}`)
+            console.log(`   workspaceId: ${pointer.workspaceId || '(未设置)'}`)
+            console.log(`   scanRunId: ${pointer.scanRunId || '(未设置)'}`)
+            console.log(`   savedAt: ${pointer.savedAt || '(未知)'}`)
+
+            if (isPointerCorrupted(pointer)) {
+              console.log(`   状态: ${POINTER_STATUS.CORRUPTED} ❌`) 
+              console.log(`   ⚠️ 指针损坏（缺少 specRoot），建议删除后重新运行平台 scan。`)
+              if (platformArgs.includes('--cleanup')) {
+                const { unlinkSync } = await import('fs')
+                unlinkSync(pointerPath)
+                console.log(`   🗑️ 已清理损坏指针。`)
+              }
+            } else if (pointer.status === POINTER_STATUS.SCAN_COMPLETED) {
+              if (isPointerStale(pointer)) {
+                console.log(`   状态: ${POINTER_STATUS.STALE} ⚠️`)
+                console.log(`   completedAt: ${pointer.completedAt}`)
+                console.log(`   scanStatus: ${pointer.scanStatus || '(未知)'}`)
+                console.log(`   ⚠️ 指针已过时（完成超过 24h），可以安全删除。`)
+                if (platformArgs.includes('--cleanup')) {
+                  const { unlinkSync } = await import('fs')
+                  unlinkSync(pointerPath)
+                  console.log(`   🗑️ 已清理过时指针。`)
+                }
+              } else {
+                console.log(`   状态: ${pointer.status} ✅`)
+                console.log(`   completedAt: ${pointer.completedAt}`)
+                console.log(`   scanStatus: ${pointer.scanStatus || '(未知)'}`)
+              }
+            } else {
+              console.log(`   状态: ${POINTER_STATUS.ACTIVE} 🔄`)
+            }
+          } catch (e) {
+            console.log(`   状态: ${POINTER_STATUS.CORRUPTED} ❌`)
+            console.log(`   ⚠️ 指针文件损坏: ${e.message}`)
+          }
+          break;
+        }
         case 'connect': {
           const url = platformArgs[0];
           if (!url) {