sillyspec 3.17.14 → 3.18.0

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.14",
+  "version": "3.18.0",
   "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/index.js

@@ -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) {

package/src/run.js

@@ -9,6 +9,7 @@ import { existsSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, read
 import { createRequire } from 'module'
 const require = createRequire(import.meta.url)
 import { ProgressManager } from './progress.js'
+import { SCAN_STATUS, POINTER_STATUS, isPointerCorrupted } from './constants.js'
 
 /**
  * 在容器/Docker 环境下，git 可能因目录所有权不匹配报 dubious ownership。
@@ -613,21 +614,29 @@ async function outputStep(stageName, stepIndex, steps, cwd, changeName, dbProjec
     }
     profileDirectives.push(`--output 只需要列出文件名，不要写长篇总结。`)
     promptText = profileDirectives.join('\n') + '\n\n' + promptText
+
+    // scanProfile 分支也要替换占位符（非 platform 模式也会走到这里）
+    const _pName = dbProjectName || basename(cwd)
+    const _specSS = platformOpts?.specRoot || join(cwd, '.sillyspec')
+    const _docsRoot = join(_specSS, 'docs', _pName)
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, _docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, join(_specSS, 'projects'))
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, join(_specSS, 'workflows'))
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, join(_specSS, 'knowledge'))
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, _specSS)
   } else {
     // 非 platform 模式也要替换占位符
-    if (stageName === 'scan') {
-      const projectName = dbProjectName || basename(cwd)
-      const specSillyspec = join(cwd, '.sillyspec')
-      const docsRoot = join(specSillyspec, 'docs', projectName)
-      const projectsRoot = join(specSillyspec, 'projects')
-      const workflowsRoot = join(specSillyspec, 'workflows')
-      const knowledgeRoot = join(specSillyspec, 'knowledge')
-      promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
-      promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
-      promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
-      promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
-      promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
-    }
+    const projectName = dbProjectName || basename(cwd)
+    const specSillyspec = join(cwd, '.sillyspec')
+    const docsRoot = join(specSillyspec, 'docs', projectName)
+    const projectsRoot = join(specSillyspec, 'projects')
+    const workflowsRoot = join(specSillyspec, 'workflows')
+    const knowledgeRoot = join(specSillyspec, 'knowledge')
+    promptText = promptText.replace(/\{DOCS_ROOT\}/g, docsRoot)
+    promptText = promptText.replace(/\{PROJECTS_ROOT\}/g, projectsRoot)
+    promptText = promptText.replace(/\{WORKFLOWS_ROOT\}/g, workflowsRoot)
+    promptText = promptText.replace(/\{KNOWLEDGE_ROOT\}/g, knowledgeRoot)
+    promptText = promptText.replace(/\{SPEC_ROOT\}/g, specSillyspec)
   }
 
   // 注入模块上下文（brainstorm/plan/execute 阶段，基于 Module Context Index）
@@ -1864,7 +1873,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     }
     // quick 阶段完成前强制检查 quicklog 是否创建
     if (stageName === 'quick') {
-      const quicklogDir = join(specBase, '.sillyspec', 'quicklog')
+      const quicklogDir = join(specBase, 'quicklog')
       const hasQuicklog = existsSync(quicklogDir) && readdirSync(quicklogDir).some(f => f.endsWith('.md') && f.startsWith('QUICKLOG'))
       if (!hasQuicklog) {
         console.error(`\n❌ quick 阶段完成校验失败：未检测到 QUICKLOG 记录文件。`)
@@ -1891,7 +1900,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
     if (stageName === 'scan' && (platformOpts.specRoot || platformOpts.runtimeRoot)) {
       try {
         stageData.scanMeta = stageData.scanMeta || {}; stageData.scanMeta.manifestWritten = false; // 默认失败
-        const { mkdirSync, writeFileSync } = await import('fs')
+        const { mkdirSync, writeFileSync, readFileSync: _readFileSync } = await import('fs')
         const { join } = await import('path')
         const { execSync } = await import('child_process')
         const manifestDir = platformOpts.specRoot
@@ -1903,10 +1912,19 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         const manifest = {
           workspace_id: platformOpts.workspaceId || null,
           scan_run_id: platformOpts.scanRunId || null,
+          source_root: cwd,
+          spec_root: platformOpts.specRoot || null,
+          runtime_root: platformOpts.runtimeRoot || null,
           source_commit: sourceCommit,
           source_commit_error: sourceCommit === null ? (scErr || 'unknown') : undefined,
           generated_at: new Date().toISOString(),
           schema_version: 1,
+          postcheck_result_path: null,
+          workflow_runs_dir: platformOpts.runtimeRoot
+            ? join(platformOpts.runtimeRoot, 'scan-runs', platformOpts.scanRunId || 'unknown', 'workflow-runs')
+            : null,
+          platform_pointer_path: join(cwd, '.sillyspec-platform.json'),
+          platform_pointer_status: POINTER_STATUS.ACTIVE,
         }
         const manifestPath = join(manifestDir, 'manifest.json')
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
@@ -1947,6 +1965,7 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         })
         if (postcheckJsonPath) {
           console.log(`📄 postcheck-result.json 已写入: ${postcheckJsonPath}`)
+          manifest.postcheck_result_path = postcheckJsonPath
         }
 
         // 将 post-check 结果写入 manifest
@@ -1958,9 +1977,19 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
         writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
         console.log(`📄 manifest.json 已更新（含 post-check 结果）`)
 
+        // 更新平台指针状态为 scan_completed
+        const pointerPath = join(cwd, '.sillyspec-platform.json')
+        try {
+          const pointer = JSON.parse(_readFileSync(pointerPath, 'utf8'))
+          pointer.status = POINTER_STATUS.SCAN_COMPLETED
+          pointer.completedAt = new Date().toISOString()
+          pointer.scanStatus = postResult.status
+          writeFileSync(pointerPath, JSON.stringify(pointer, null, 2) + '\n')
+        } catch {}
+
         // failed_post_check 时强制阻止 clean success
         if (postResult.status === 'failed_post_check') {
-          stageData.status = 'failed_post_check'
+          stageData.status = SCAN_STATUS.FAILED_POST_CHECK
           stageData.completedAt = new Date().toLocaleString('zh-CN',{hour12:false})
           await pm._write(cwd, progress, changeName)
           console.error(`\n❌ scan post-check 失败，状态设为 failed_post_check。不允许 clean success。`)
@@ -2135,7 +2164,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
               console.log(rp.prompt)
             }
           }
-          const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'verify', step: steps[currentIdx]?.name })
+          const saved = saveWorkflowRun(result, {
+            cwd,
+            source: 'run.js',
+            stage: 'scan',
+            step: steps[currentIdx]?.name,
+            ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
+            ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
+          })
           if (saved) console.log(`📁 结果已归档：${saved}`)
         }
         if (anyFailed) {
@@ -2165,7 +2201,14 @@ async function completeStep(pm, progress, stageName, cwd, outputText, inputText
             console.log(`   └─ ${f}`)
           }
         }
-        const saved = saveWorkflowRun(result, { cwd, source: 'run.js', stage: 'archive', step: steps[currentIdx]?.name })
+        const saved = saveWorkflowRun(result, {
+          cwd,
+          source: 'run.js',
+          stage: 'archive',
+          step: steps[currentIdx]?.name,
+          ...(platformOpts.runtimeRoot ? { runtimeRoot: platformOpts.runtimeRoot } : {}),
+          ...(platformOpts.scanRunId ? { scanRunId: platformOpts.scanRunId } : {})
+        })
         if (saved) console.log(`📁 结果已归档：${saved}`)
       }
     } catch (e) {