ultra-builder-pro-cli 0.7.0 → 0.8.1

package/adapters/codex.js

@@ -33,6 +33,7 @@ const {
   buildPlugin,
   installAgents,
 } = require('./_shared/codex-assets.cjs');
+const provenance = require('./_shared/provenance.cjs');
 
 const MCP_SERVER_NAME = PLUGIN_NAME;
 const SOURCE_TAG = 'ubp';
@@ -40,6 +41,7 @@ const MARKER_BEGIN = '# >>> ultra-builder-pro managed block — do not edit by h
 const MARKER_END = '# <<< ultra-builder-pro managed block';
 const RUNTIME_MANIFEST_DIR = 'ultra-builder-pro';
 const RUNTIME_MANIFEST_FILE = 'install-manifest.json';
+const PROVENANCE_FILE = 'provenance.json';
 const HOOK_ADAPTER_RELATIVE = path.join('hooks', 'adapters', 'codex.py');
 
 function resolveTarget(ctx = {}) {
@@ -355,6 +357,30 @@ function install(ctx = {}) {
     agents: agents.installed,
     hookCacheVersions,
   });
+  const source = provenance.packageSource(repoRoot);
+  const provenanceFile = path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE);
+  const provenanceManifest = provenance.writeProvenance({
+    file: provenanceFile,
+    adapter: 'codex',
+    ...source,
+    roots: { plugin: pluginRoot, config: configDir },
+    assets: [
+      ...provenance.assetRefsForTree('plugin', pluginRoot, {
+        exclude: ['.ubp-managed'],
+      }),
+      ...agents.installed.map((file) => ({ root: 'config', path: path.join('agents', file) })),
+      { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+    ],
+    contracts: {
+      plugin_manifest: { root: 'plugin', path: '.codex-plugin/plugin.json' },
+      mcp_registration: { root: 'plugin', path: '.mcp.json' },
+      mcp_launcher: { root: 'plugin', path: 'runtime/launch.cjs' },
+      hooks_manifest: { root: 'plugin', path: 'hooks/hooks.json' },
+      hook_adapter: { root: 'plugin', path: HOOK_ADAPTER_RELATIVE },
+      runtime_manifest: { root: 'config', path: path.join(RUNTIME_MANIFEST_DIR, RUNTIME_MANIFEST_FILE) },
+    },
+  });
+  provenanceManifest.file = provenanceFile;
 
   return {
     target: configDir,
@@ -365,10 +391,70 @@ function install(ctx = {}) {
     hookCompatibility,
     legacy,
     manifestFile,
+    provenance: provenanceManifest,
     config: { updated: legacy.configUpdated },
   };
 }
 
+function doctor(ctx = {}) {
+  const configDir = resolveTarget(ctx);
+  const pluginRoot = resolvePluginRoot(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  const marketplaceFile = resolveMarketplaceFile(ctx);
+  const source = provenance.packageSource(repoRoot);
+  const report = provenance.inspectProvenance({
+    file: path.join(configDir, RUNTIME_MANIFEST_DIR, PROVENANCE_FILE),
+    expectedAdapter: 'codex',
+    expectedPackageVersion: source.packageInfo.version,
+  });
+
+  let runtimeManifest = null;
+  try {
+    runtimeManifest = readRuntimeManifest(configDir);
+  } catch (error) {
+    report.issues.push({ code: 'RUNTIME_MANIFEST_INVALID', message: error.message });
+  }
+  const runtimeManifestOk = runtimeManifest?.source === SOURCE_TAG
+    && runtimeManifest.adapter === 'codex'
+    && runtimeManifest.plugin?.root === pluginRoot
+    && typeof runtimeManifest.plugin?.version === 'string';
+  if (!runtimeManifestOk && !report.issues.some((entry) => entry.code === 'RUNTIME_MANIFEST_INVALID')) {
+    report.issues.push({ code: 'RUNTIME_MANIFEST_INVALID', path: runtimeManifestFile(configDir) });
+  }
+  report.checks.runtime_manifest = { status: runtimeManifestOk ? 'pass' : 'fail' };
+
+  let marketplaceOk = false;
+  try {
+    const marketplace = loadMarketplace(marketplaceFile);
+    const entry = marketplace.plugins.find((plugin) => plugin?.name === PLUGIN_NAME);
+    marketplaceOk = entry?.source?.source === 'local'
+      && entry.source.path === `./plugins/${PLUGIN_NAME}`;
+  } catch (error) {
+    report.issues.push({ code: 'MARKETPLACE_REGISTRATION_INVALID', message: error.message });
+  }
+  if (!marketplaceOk && !report.issues.some((entry) => entry.code === 'MARKETPLACE_REGISTRATION_INVALID')) {
+    report.issues.push({ code: 'MARKETPLACE_REGISTRATION_INVALID', path: marketplaceFile });
+  }
+  report.checks.marketplace = { status: marketplaceOk ? 'pass' : 'fail' };
+
+  let hookTargetsOk = runtimeManifestOk;
+  if (runtimeManifestOk) {
+    const cacheRoot = pluginCacheRoot(configDir, runtimeManifest.marketplace?.name || 'personal');
+    const currentCacheRequired = shouldRunPluginCli(ctx);
+    for (const version of runtimeManifest.hook_cache_versions || []) {
+      if (version === runtimeManifest.plugin.version && !currentCacheRequired) continue;
+      const adapter = path.join(cacheRoot, version, HOOK_ADAPTER_RELATIVE);
+      if (!fs.existsSync(adapter)) {
+        hookTargetsOk = false;
+        report.issues.push({ code: 'HOOK_TARGET_MISSING', version, path: adapter });
+      }
+    }
+  }
+  report.checks.hook_targets = { status: hookTargetsOk ? 'pass' : 'fail' };
+  if (report.status !== 'missing') report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
+  return report;
+}
+
 function removeManagedAgents(configDir, manifest) {
   const agentRoot = path.join(configDir, 'agents');
   const requested = manifest && Array.isArray(manifest.agents)
@@ -440,6 +526,7 @@ module.exports = {
   resolveMarketplaceFile,
   install,
   uninstall,
+  doctor,
   _internal: {
     stripManagedBlock,
     hasManagedBlock,

package/adapters/opencode.js

@@ -15,6 +15,7 @@ const {
   writeAtomic,
 } = require('./_shared/file-ops.cjs');
 const { buildMcpRuntime } = require('./_shared/codex-assets.cjs');
+const provenance = require('./_shared/provenance.cjs');
 const {
   CORE_PUBLIC_SKILLS,
   skillsForRuntime,
@@ -34,6 +35,7 @@ const SOURCE_TAG = 'ubp';
 const BUNDLE_DIR = '.ultra-builder-pro';
 const MANAGED_TEXT_MARKER = '<!-- ultra-builder-pro:managed -->';
 const PLUGIN_MARKER = '// Managed by Ultra Builder Pro.';
+const PROVENANCE_FILE = 'provenance.json';
 const COMMAND_NAMES = CORE_PUBLIC_SKILLS.filter((name) => name !== 'ultra-review');
 
 function resolveTarget(ctx = {}) {
@@ -515,6 +517,69 @@ function install(ctx = {}) {
   delete next[LEGACY_SENTINEL_KEY];
   writeAtomic(configFile, JSON.stringify(next, null, 2) + '\n');
   report.config.updated = true;
+  const source = provenance.packageSource(repoRoot);
+  const bundleAssets = provenance.assetRefsForTree('config', bundleRoot, {
+    exclude: [PROVENANCE_FILE],
+  }).map((asset) => ({ ...asset, path: path.join(BUNDLE_DIR, asset.path) }));
+  const skillMarkers = skillsForRuntime('opencode').map((name) => ({
+    root: 'config', path: path.join('skills', name, '.ubp-managed'),
+  }));
+  const provenanceFile = path.join(bundleRoot, PROVENANCE_FILE);
+  report.provenance = provenance.writeProvenance({
+    file: provenanceFile,
+    adapter: 'opencode',
+    ...source,
+    roots: { config: target },
+    assets: [
+      ...report.copied.commands.map((file) => ({ root: 'config', path: path.join('commands', file) })),
+      ...report.copied.skills.map((file) => ({ root: 'config', path: path.join('skills', file) })),
+      ...skillMarkers,
+      ...report.copied.agents.map((file) => ({ root: 'config', path: path.join('agents', file) })),
+      { root: 'config', path: path.join('plugins', 'ultra-builder-pro.js') },
+      ...bundleAssets,
+    ],
+    contracts: {
+      host_plugin: { root: 'config', path: path.join('plugins', 'ultra-builder-pro.js') },
+      mcp_config: { root: 'config', path: 'opencode.json' },
+      mcp_launcher: { root: 'config', path: path.join(BUNDLE_DIR, 'runtime', 'launch.cjs') },
+    },
+  });
+  report.provenance.file = provenanceFile;
+  return report;
+}
+
+function doctor(ctx = {}) {
+  const target = resolveTarget(ctx);
+  const repoRoot = resolveRepoRoot(ctx);
+  const source = provenance.packageSource(repoRoot);
+  const report = provenance.inspectProvenance({
+    file: path.join(target, BUNDLE_DIR, PROVENANCE_FILE),
+    expectedAdapter: 'opencode',
+    expectedPackageVersion: source.packageInfo.version,
+  });
+  const configFile = path.join(target, 'opencode.json');
+  const expectedLauncher = path.join(target, BUNDLE_DIR, 'runtime', 'launch.cjs');
+  let registrationOk = false;
+  try {
+    const config = readJsonSafe(configFile);
+    const entry = config.mcp && config.mcp[MCP_SERVER_NAME];
+    registrationOk = entry?.type === 'local'
+      && entry.enabled === true
+      && Array.isArray(entry.command)
+      && entry.command[0] === process.execPath
+      && entry.command[1] === expectedLauncher;
+  } catch (error) {
+    report.issues.push({ code: 'MCP_REGISTRATION_INVALID', message: error.message });
+  }
+  if (!registrationOk && !report.issues.some((entry) => entry.code === 'MCP_REGISTRATION_INVALID')) {
+    report.issues.push({
+      code: 'MCP_REGISTRATION_INVALID',
+      path: configFile,
+      expected_launcher: expectedLauncher,
+    });
+  }
+  report.checks.registration = { status: registrationOk ? 'pass' : 'fail' };
+  if (report.status !== 'missing') report.status = report.issues.length === 0 ? 'healthy' : 'degraded';
   return report;
 }
 
@@ -590,4 +655,5 @@ module.exports = {
   resolveTarget,
   install,
   uninstall,
+  doctor,
 };

package/adapters/tests/codex.test.cjs

@@ -362,3 +362,40 @@ test('uninstall removes only UBP-managed plugin and agents', () => {
     cleanup(layout);
   }
 });
+
+test('doctor checks the current Codex cache hook target for a CLI-managed global install', () => {
+  const layout = mkLayout();
+  try {
+    install(layout);
+    const runtimeManifest = JSON.parse(fs.readFileSync(
+      path.join(layout.configDir, 'ultra-builder-pro', 'install-manifest.json'),
+      'utf8',
+    ));
+    const version = runtimeManifest.plugin.version;
+    const cacheAdapter = path.join(
+      codex._internal.pluginCacheRoot(layout.configDir, 'personal'),
+      version,
+      'hooks',
+      'adapters',
+      'codex.py',
+    );
+    const doctorCtx = {
+      homeDir: layout.homeDir,
+      scope: 'global',
+      repoRoot: REPO_ROOT,
+      runPluginCli: true,
+    };
+
+    const degraded = codex.doctor(doctorCtx);
+    assert.equal(degraded.status, 'degraded');
+    assert.ok(degraded.issues.some((entry) => (
+      entry.code === 'HOOK_TARGET_MISSING' && entry.version === version
+    )));
+
+    fs.mkdirSync(path.dirname(cacheAdapter), { recursive: true });
+    fs.copyFileSync(path.join(layout.pluginRoot, 'hooks', 'adapters', 'codex.py'), cacheAdapter);
+    assert.equal(codex.doctor(doctorCtx).status, 'healthy');
+  } finally {
+    cleanup(layout);
+  }
+});

package/agents/debugger.md

@@ -115,6 +115,18 @@ If **3 consecutive fix attempts fail**, and each reveals new problems in differe
 {test output proving fix resolves the issue, no regressions}
 ```
 
+When the parent assigns an Ultra `incident` change, also map the verified report
+into the exact durable `diagnosis.md` contract:
+
+- `Reproduction`: the smallest repeatable symptom and exact trigger;
+- `Hypotheses`: falsifiable hypotheses and the evidence that accepted/rejected each;
+- `Root cause`: the earliest incorrect state and why it occurred;
+- `Regression test`: the failing-first test and its final passing command;
+- `Recovery`: rollback, retry, repair, or operator action when applicable.
+
+Return this content to the primary agent. Do not write `.ultra/state.db` or claim
+incident convergence; the primary agent owns the change artifact and verification.
+
 ## Rules
 
 - Never guess. Every claim must have evidence from code or output.

package/bin/install.js

@@ -16,6 +16,8 @@
  *   -g, --global                                  install to runtime's global config dir
  *   -l, --local                                   install into current working directory
  *   -u, --uninstall                               remove installed assets
+ *   -d, --doctor                                  inspect installation provenance without mutation
+ *   --json                                        emit machine-readable doctor output
  *   -c, --config-dir <path>                       override config directory
  *   -h, --help                                    show help
  */
@@ -77,6 +79,8 @@ function printHelp() {
 
   ${paint('yellow', 'Other:')}
     ${paint('cyan', '-u, --uninstall')}    remove installed assets
+    ${paint('cyan', '-d, --doctor')}       verify installed version, provenance, managed assets, and live entry points
+    ${paint('cyan', '--json')}             emit machine-readable doctor output (doctor only)
     ${paint('cyan', '-c, --config-dir')}   override runtime's config directory (string path)
     ${paint('cyan', '-h, --help')}         show this help
     ${paint('cyan', '-v, --version')}      show CLI version
@@ -90,6 +94,9 @@ function printHelp() {
 
     ${paint('dim', '# Uninstall from OpenCode')}
     npx ultra-builder-pro-cli --opencode --global --uninstall
+
+    ${paint('dim', '# Verify all host installations without changing them')}
+    npx ultra-builder-pro-cli --all --global --doctor
 `);
 }
 
@@ -100,6 +107,8 @@ function parseArgs(argv) {
     global: false,
     local: false,
     uninstall: false,
+    doctor: false,
+    json: false,
     help: false,
     version: false,
     configDir: null,
@@ -117,6 +126,8 @@ function parseArgs(argv) {
       case '-g': case '--global': flags.global = true; break;
       case '-l': case '--local': flags.local = true; break;
       case '-u': case '--uninstall': flags.uninstall = true; break;
+      case '-d': case '--doctor': flags.doctor = true; break;
+      case '--json': flags.json = true; break;
       case '-h': case '--help': flags.help = true; break;
       case '-v': case '--version': flags.version = true; break;
       case '-c': case '--config-dir':
@@ -178,13 +189,15 @@ async function main() {
     return;
   }
 
-  printBanner();
-
   if (flags.help) {
+    printBanner();
     printHelp();
     return;
   }
 
+  if (flags.doctor && flags.uninstall) bail('cannot combine --doctor and --uninstall');
+  if (flags.json && !flags.doctor) bail('--json is available only with --doctor');
+
   if (runtimes.length === 0) {
     bail('no runtime selected; use --claude / --opencode / --codex / --all');
   }
@@ -193,15 +206,57 @@ async function main() {
   const repoRoot = path.resolve(__dirname, '..');
   const configDir = flags.configDir ? expandTilde(flags.configDir) : null;
 
-  const mode = flags.uninstall ? 'uninstall' : 'install';
-  console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
-  console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
-  console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
-  if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
-  console.log();
+  if (!flags.json) printBanner();
+
+  const mode = flags.doctor ? 'doctor' : flags.uninstall ? 'uninstall' : 'install';
+  if (!flags.json) {
+    console.log(`  ${paint('bold', 'Mode:')}     ${mode}`);
+    console.log(`  ${paint('bold', 'Scope:')}    ${scope}`);
+    console.log(`  ${paint('bold', 'Runtimes:')} ${runtimes.join(', ')}`);
+    if (configDir) console.log(`  ${paint('bold', 'ConfigDir:')} ${configDir}`);
+    console.log();
+  }
 
   const ctx = { repoRoot, scope, configDir, homeDir: os.homedir() };
 
+  if (flags.doctor) {
+    const reports = [];
+    for (const runtime of runtimes) {
+      const adapter = loadAdapter(runtime);
+      try {
+        if (typeof adapter.doctor !== 'function') throw new Error('adapter does not expose doctor()');
+        reports.push(await adapter.doctor(ctx));
+      } catch (error) {
+        reports.push({
+          adapter: runtime,
+          status: 'degraded',
+          manifest_path: null,
+          checks: {},
+          issues: [{ code: 'DOCTOR_FAILED', message: error.message }],
+        });
+      }
+    }
+    const output = {
+      status: reports.every((report) => report.status === 'healthy') ? 'healthy' : 'degraded',
+      reports,
+    };
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+    } else {
+      for (const report of reports) {
+        const color = report.status === 'healthy' ? 'green' : 'red';
+        console.log(`  ${paint(color, report.status === 'healthy' ? '✓' : '✗')} ${report.adapter}: ${report.status}`);
+        for (const finding of report.issues || []) {
+          const location = finding.path ? ` (${finding.path})` : '';
+          console.log(`      ${finding.code}${location}`);
+        }
+      }
+      console.log();
+    }
+    if (output.status !== 'healthy') process.exitCode = 2;
+    return;
+  }
+
   let failed = 0;
   for (const runtime of runtimes) {
     const adapter = loadAdapter(runtime);

package/commands/ultra-change.md

@@ -28,8 +28,9 @@ mcp_tools_required:
 1. 先查 active/blocked change，匹配则恢复，避免重复创建。
 2. 按 `quick / standard / major / incident` 分类并声明 docs impact。
 3. 调 `change.create`，为 change 创建至少一个带 `change_id` 的 task。
-4. standard/major 写 delta + plan；调 `change.context` 编译最小上下文。
-5. 路由到 `/ultra-dev`、`/ultra-test`、`/ultra-review`、`/ultra-deliver`。
+4. standard/major 写 delta + plan；incident 完成结构化 `diagnosis.md`。
+5. 调 `change.context` 编译最小上下文；incident 先走 debugger 诊断切片。
+6. 路由到 `/ultra-dev`、`/ultra-test`、`/ultra-review`、`/ultra-deliver`。
 
 Memory 与代码图谱只允许以外部 provider 元数据引用出现；本命令不保存 provider
 正文，也不自动刷新外部 provider。

package/docs/ARCHITECTURE.md

@@ -141,6 +141,14 @@ but all require completed linked tasks, current context, declared documentation
 impact, and no open incident. Memory and graph payloads never enter Ultra;
 `context_snapshots.provider_refs_json` stores metadata references only.
 
+`incident` is the canonical debug lane. Creating one also registers a durable
+`diagnosis.md` artifact with five mandatory sections: reproduction, hypotheses,
+root cause, regression test, and recovery. Convergence validates the artifact
+structure and refreshes its content hash, so a debugger result that exists only
+in chat cannot satisfy delivery. A host-native debugger may produce the bounded
+analysis, but the primary agent owns the artifact, linked task, regression
+evidence, and final convergence decision.
+
 Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
 swallowed warning. `system.doctor` is read-only by default and performs only
@@ -168,7 +176,33 @@ This admission gate is the smallest piece that prevents two agents from
 silently double-writing the same task — it is part of the v0.1 minimum
 execution layer, not deferred to Phase 5.
 
-## 6. Two timelines — rule layer vs execution layer
+## 6. Compaction recovery — checkpoint as a validated consumer
+
+`workflow_checkpoint.py` validates the current non-terminal workflow and writes
+a schema-versioned checkpoint atomically before compaction. On resume,
+`workflow_resume.py` reads both the live workflow and checkpoint defensively,
+rejects corrupt, non-object, schema-mismatched, or terminal candidates, and
+selects the newest valid state. A newer live state wins; a newer checkpoint can
+atomically restore a missing or older live state before context is re-injected.
+The checkpoint is therefore a recovery artifact and consumer, never a second
+durable authority alongside `.ultra/state.db`.
+
+## 7. Installation provenance — read-only cross-host diagnosis
+
+Every Claude Code, OpenCode, and Codex adapter writes a normalized
+`provenance.json` for the assets it owns. The manifest records adapter/package
+identity, source metadata, per-file SHA-256 hashes, an aggregate digest, and the
+host-specific plugin, MCP, hook, launcher, and runtime contracts expected at
+that install scope. It never attributes a package to an enclosing consumer
+repository commit.
+
+`ubp --doctor [--json]` is read-only: it recomputes hashes and validates those
+entry points, returning a non-zero degraded result for missing/corrupt
+provenance, content drift, or broken host wiring. This is separate from
+`system.doctor`, which diagnoses project state, projection, incidents, sessions,
+and backup-first workflow recovery.
+
+## 8. Two timelines — rule layer vs execution layer
 
 The roadmap separates two concerns that compete for the same surface
 area (D13):
@@ -196,7 +230,7 @@ value from "skills + tasks survive across sessions" long before they get
 value from "ten agents in parallel." Each milestone is independently
 shippable; downstream slip never blocks an earlier release.
 
-## 7. Where to look next
+## 9. Where to look next
 
 | Question                                           | File                                                |
 |----------------------------------------------------|-----------------------------------------------------|
@@ -206,7 +240,7 @@ shippable; downstream slip never blocks an earlier release.
 | What does a tasks.json look like after projection? | [`spec/fixtures/valid/tasks.v4.5.json`](../spec/fixtures/valid/tasks.v4.5.json) |
 | Phase-by-phase work breakdown + decision log       | [`docs/PLAN.zh-CN.md`](./PLAN.zh-CN.md)             |
 
-## 8. Verifying the architecture
+## 10. Verifying the architecture
 
 Every contract on this page is enforced by `npm run test:spec`:
 

package/docs/PLAN.zh-CN.md

@@ -1,6 +1,6 @@
 # ultra-builder-pro-cli — 历史执行计划与决策日志
 
-> **2026-07-17 当前生效边界（D50-D52，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
+> **2026-07-17 当前生效边界（D50-D53，覆盖下文旧 Phase 6/7 的内置图谱、memory 与 runtime 设计）**：
 > Ultra Builder Pro 不再拥有 `memory.*`、recall、prompt/transcript/observation/summary
 > 收集 hook 或私有 agent memory。跨会话记忆全部交给独立安装的 cloud-mem/claude-mem。
 > 插件只保留 12 个 Ultra 公共 workflow（新增 daily `ultra-change` 与诊断
@@ -10,8 +10,9 @@
 > 采用各自 native plugin 呈现，其他旧 runtime adapter 已退役。下文所有与此冲突的
 > memory/hindsight 章节仅作为历史实施记录，不再是当前需求或运行时契约。
 
-**当前状态**：v0.7.0 发布候选；三宿主 native plugin、29 个 live MCP tool、
-schema 9.0（15 表）、持续 change/context/convergence/doctor 已落地；npm 发布由
+**当前状态**：v0.8.1；三宿主 native plugin、29 个 live MCP tool、
+schema 9.0（15 表）、持续 change/context/convergence/doctor、incident debug lane、
+checkpoint 恢复消费与跨宿主安装 provenance/doctor 已落地；npm 发布由
 `v*.*.*` tag 触发。以下 Phase 0-9 正文保留为 2026-04 的实施历史，不再作为
 当前 runtime 或发布状态的事实来源。
 **历史版本**：0.3.1-plan · 2026-04-17 Codex 第二轮评审收尾
@@ -27,7 +28,7 @@ schema 9.0（15 表）、持续 change/context/convergence/doctor 已落地；np
 - **Phase 4.6 拆 a/b**（R6 + D35）：v0.1 只跑 smoke flow，full conformance 推 v0.2
 - **Codex 第二轮结论**："小改后开工"（tl;dr）；本版已完成小改
 
-**总决策数**：D1-D52（当前边界以 D50-D52 为准）
+**总决策数**：D1-D53（当前边界以 D50-D53 为准）
 **总风险数**：R1-R32（v0.3.1 新增 R25-R32 共 8 条）
 
 ---
@@ -1639,6 +1640,7 @@ Week 18      buffer（ship 中任何 Phase 的 25% 滑动吃掉）
 | **D50** | **2026-07-15** | **重划插件与记忆边界**：Claude Code、Codex、OpenCode 改为各自 native plugin；只打包 10 个 Ultra 公共 workflow、4 个 agent-only 规则 skill 与宿主专属 collab companion；删除 6 个外部 skill、recall、Impeccable 残留、Ultra memory MCP/store/wrapper/capture hooks；持久记忆由独立 cloud-mem/claude-mem 负责；用户 handbook 通过可预览、可备份的 managed block 显式同步 | 用户确认最终方案；运行时 allowlist、conformance、hook 与 handbook 回归测试共同锁定边界 |
 | **D51** | **2026-07-17** | **runtime 收敛为 Claude Code、OpenCode、Codex**：删除第四 runtime 的 adapter、安装参数、collab skill、prompt、schema、pricing、调度与测试面；`ultra-verify` 改为当前宿主主责加单一只读外部顾问 | 用户确认不再需要第四 runtime；0.6.0 退役契约阻止其重新进入活跃源码或发布包 |
 | **D52** | **2026-07-17** | **初始交付后进入持续变更闭环**：新增 `ultra-change` / `ultra-doctor`、change/context/artifact/trace/incident/projection/consumer 状态、delta-first spec、确定性 convergence 与 baseline reconciliation；删除内置 code-graph watcher 和通用命令代理，Memory/图谱只保留外部 provider 元数据引用 | 用户确认采用最佳组合落地；解决日常小改导致 spec/context 漂移、投影失败静默和异常无恢复证据的问题 |
+| **D53** | **2026-07-17** | **Harness 缺口一次性闭环**：`incident` 成为带五段 `diagnosis.md` 结构门禁的 canonical debug lane；compact checkpoint 由 resume 消费、校验、择新并原子恢复；三宿主安装写 normalized provenance，`ubp --doctor` 只读校验 asset hash 与 plugin/hook/MCP/runtime contract | 将 GSD 的 debug/fresh context、GStack 的 checkpoint/readiness 与 ECC 的 doctor/provenance 思路收敛为 Ultra 自有契约；Memory 与图谱继续由外部 provider 所有，且不恢复任何已退役 surface |
 
 ---
 

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -41,7 +41,7 @@ primary verification.
 |---|---|---|---|
 | Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` |
 | Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` |
-| Compaction recovery | FULL, `PreCompact` + resume matcher | FULL, native compacting context | FULL, `PreCompact` + `PostCompact` |
+| Compaction recovery | FULL, validated checkpoint + resume/restore matcher | FULL, native compacting context | FULL, validated checkpoint + `PostCompact` restore |
 | Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` |
 | Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL |
 
@@ -83,6 +83,9 @@ loading, and user interaction remain host-native surfaces.
 | Removes stale managed assets | FULL | FULL | FULL |
 | Preserves unrelated config | FULL | FULL | FULL |
 | Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers |
+| Normalized install provenance | FULL | FULL | FULL |
+| Read-only `ubp --doctor` | FULL | FULL | FULL |
+| Asset-content and host-contract drift detection | FULL | FULL | FULL |
 
 ## 7. Verification sources
 
@@ -95,5 +98,9 @@ loading, and user interaction remain host-native surfaces.
   from re-entering active product surfaces.
 - `adapters/_shared/tests/handbook.test.cjs` verifies host rendering, backup,
   migration, and idempotency.
+- `adapters/_shared/tests/provenance.test.cjs` verifies normalized manifests,
+  content hashes, source attribution, corruption handling, and contract drift.
+- `tests/install.test.cjs` verifies healthy three-host doctor output and
+  host-specific hook/MCP degradation after controlled tampering.
 
 Any capability claim elsewhere must match current adapter code and these tests.

package/hooks/README.md

@@ -9,8 +9,8 @@ bounded to the relevant Ultra projection or a non-terminal workflow.
 | Session start | `health_check.py` | Read-only integrity, incident, projection, session, and change-artifact checks |
 | Session start | `workflow_context.py` | Inject baseline/active workflow/change context and filtered provider metadata references |
 | Before edit | `active_task_context.py` | Protect `tasks.json` projection and restate an active task boundary |
-| Before compact | `workflow_checkpoint.py` | Atomically save a minimal workflow checkpoint |
-| After compact/resume | `workflow_resume.py` | Re-inject the current workflow boundary |
+| Before compact | `workflow_checkpoint.py` | Validate and atomically save a minimal workflow checkpoint |
+| After compact/resume | `workflow_resume.py` | Select the newest valid live/checkpoint state, restore it atomically when needed, and re-inject the boundary |
 | Stop | `pre_stop_check.py` | Block once when the Ultra workflow is incomplete |
 | Subagent lifecycle | `subagent_tracker.py` | Append lifecycle evidence under `.ultra/runtime/` |
 
@@ -18,6 +18,10 @@ The plugin deliberately does not capture prompts, tool observations, transcripts
 cross-session memory or code-graph content. Generic command blocking and post-edit policy are
 user/repository governance. Persistent Memory/graph content belongs to separately installed providers.
 
+The checkpoint is a recovery artifact, not a second authority. A valid newer
+live workflow wins; a newer valid checkpoint may restore a missing or older
+live file; corrupt, non-object, or terminal checkpoints are ignored.
+
 Runtime wiring:
 
 - Claude Code: native `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}` paths.

package/hooks/workflow_checkpoint.py

@@ -11,6 +11,17 @@ from pathlib import Path
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -28,7 +39,10 @@ def main() -> None:
         except (OSError, json.JSONDecodeError) as exc:
             print(f"[workflow_checkpoint] cannot read {state_file}: {exc}", file=sys.stderr)
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        if not valid_workflow(state):
+            print(f"[workflow_checkpoint] invalid workflow state in {state_file}", file=sys.stderr)
+            break
+        if state.get("status") in TERMINAL:
             break
         runtime_dir = root / ".ultra" / "runtime"
         runtime_dir.mkdir(parents=True, exist_ok=True)