scene-capability-engine 3.6.32 → 3.6.37

package/docs/zh/README.md

@@ -1,31 +1,42 @@
 # SCE 文档总览
 
-本页仅保留高价值入口，帮助你快速完成从接入到规模化交付。
+本页只保留高价值入口，帮助你从接入、集成到规模化交付快速找到主路径。
 
 ---
 
 ## 优先入口
 
 - [快速开始](quick-start.md)
+- [AI 工具快速开始](../quick-start-with-ai-tools.md)
 - [命令参考](../command-reference.md)
 - [常见问题](../faq.md)
 - [故障排除](../troubleshooting.md)
 
 ---
 
-## 交付主路径
+## 核心交付路径
 
 - [Spec 工作流](../spec-workflow.md)
 - [自动闭环指南](../autonomous-control-guide.md)
 - [多 Agent 协同指南](../multi-agent-coordination-guide.md)
-- [Spec 协作指南](../spec-collaboration-guide.md)
-- [Spec 锁机制指南](../spec-locking-guide.md)
+- [场景运行时指南](../scene-runtime-guide.md)
+- [Value 可观测指南](../value-observability-guide.md)
+- [本轮重构完成总结与下一轮路线图](refactor-completion-roadmap.md)
+
+---
+
+## 治理与发布
+
+- [Errorbook 注册表指南](../errorbook-registry.md)
+- [安全治理默认基线](../security-governance-default-baseline.md)
+- [文档治理](../document-governance.md)
+- [发布检查清单](../release-checklist.md)
+- [发布归档](../releases/README.md)
 
 ---
 
 ## 场景化能力与 Moqui
 
-- [场景运行时指南](../scene-runtime-guide.md)
 - [Moqui 模板核心库 Playbook](../moqui-template-core-library-playbook.md)
 - [Moqui 能力矩阵](../moqui-capability-matrix.md)
 - [Moqui 标准重建指南](../moqui-standard-rebuild-guide.md)
@@ -33,27 +44,12 @@
 
 ---
 
-## 治理、质量与发布
-
-- [文档治理](../document-governance.md)
-- [安全治理默认基线](../security-governance-default-baseline.md)
-- [Errorbook 注册表指南](../errorbook-registry.md)
-- [发布检查清单](release-checklist.md)
-- [发布归档](releases/README.md)
-
----
-
-## 平台管理与运维
+## 平台与集成
 
 - [环境管理指南](../environment-management-guide.md)
 - [多仓库管理指南](../multi-repo-management-guide.md)
 - [团队协作指南](../team-collaboration-guide.md)
 - [手动工作流指南](../manual-workflows-guide.md)
-
----
-
-## AI 工具集成
-
 - [Cursor 集成](tools/cursor-guide.md)
 - [Claude Code 集成](tools/claude-guide.md)
 - [Windsurf 集成](tools/windsurf-guide.md)
@@ -62,20 +58,21 @@
 
 ---
 
-## 补充阅读
+## Language
 
-- [Value 可观测指南](value-observability-guide.md)
-- [架构说明](../architecture.md)
-- [开发者指南](../developer-guide.md)
-- [社区入口](../community.md)
+- [English Docs Hub](../README.md)
 
 ---
 
-## Language
+## 社区
 
-- [English Docs Hub](../README.md)
+- [社区入口](../community.md)
+- [GitHub Discussions](https://github.com/heguangyong/scene-capability-engine/discussions)
+- [GitHub Issues](https://github.com/heguangyong/scene-capability-engine/issues)
 
 ---
 
-**版本**：3.3.26  
-**最后更新**：2026-03-02
+**版本**：3.6.34
+**最后更新**：2026-03-08
+
+

package/docs/zh/refactor-completion-roadmap.md

@@ -0,0 +1,116 @@
+# 本轮重构完成总结与下一轮路线图
+
+## 范围
+
+本文件用于记录 `3.6.33` 这一轮重构的完成状态，并明确下一阶段的工程方向。
+
+当前稳定提交：
+
+- `0c9594d` `refactor(auto): finalize close-loop governance split and docs refresh`
+- `0fb49b7` `refactor(handoff): extract capability matrix service`
+- `8ebc5bc` `release: 3.6.33`
+
+## 什么算完成
+
+这一轮重构之所以可以判定为完成，不是因为 `lib/commands/auto.js` 里一个大函数都不剩，而是因为最核心的自动交付主链已经不再以它为中心。
+
+本轮已完成下沉：
+
+- `lib/auto/close-loop-controller-service.js`
+- `lib/auto/close-loop-batch-service.js`
+- `lib/auto/close-loop-program-service.js`
+- `lib/auto/observability-service.js`
+- `lib/auto/program-summary.js`
+- `lib/auto/program-output.js`
+- `lib/auto/batch-output.js`
+- `lib/auto/program-governance-helpers.js`
+- `lib/auto/program-governance-loop-service.js`
+- `lib/auto/program-auto-remediation-service.js`
+- `lib/auto/output-writer.js`
+- `lib/auto/handoff-capability-matrix-service.js`
+
+本轮同步完成的收口工作：
+
+- README 与 docs hub 重组
+- governance summary 真实回归修复
+- governance weekly-ops session telemetry 修复
+- session stats `criteria.days` 字段修复
+
+## 架构变化
+
+在本轮之前：
+
+- `lib/commands/auto.js` 同时承担命令注册和大量主执行逻辑。
+- program / governance 行为一旦调整，回归风险会很高，因为职责耦合过重。
+
+在本轮之后：
+
+- `lib/commands/auto.js` 更接近命令层壳子与 wrapper。
+- 主要交付链路已经迁移到 `lib/auto/`。
+- `auto-handoff` 也已经拥有了第一个完整专题边界。
+
+这就是为什么即使 `auto.js` 仍然很大，这一轮也可以被定义为完成。
+
+## 为什么有些工作被明确延后
+
+不是 `auto.js` 里剩下的每个函数，都值得马上继续拆。
+
+本轮明确延后的内容：
+
+- 收益很低的 helper 搬运
+- 一旦切出去就容易引入回归的 `auto-handoff` 零碎微边界
+- 对长期维护性帮助不大的纯 cosmetic 收缩
+
+本轮执行标准是：
+
+- 保留能形成长期 service 边界的拆分
+- 当下一刀的收益低于回归风险时，立即停止
+
+## 剩余高价值方向
+
+下一轮真正值得继续做的，不再是 close-loop 主链，而是 `auto-handoff` 及少量发布治理支持域。
+
+剩余高价值主题：
+
+1. `auto-handoff` release evidence 子域
+2. `auto-handoff` release gate history 子域
+3. `auto-handoff` release notes / evidence review 渲染子域
+4. `auto-handoff` baseline / coverage snapshot 子域
+
+## 建议的下一轮
+
+下一轮建议明确命名为 `auto-handoff` 专题重构，而不是继续做泛化的 `auto.js` 清理。
+
+建议顺序：
+
+1. `release evidence` 子域
+2. `release gate history` 子域
+3. `release notes / evidence review` 渲染子域
+4. `baseline / coverage snapshot` 子域
+
+每个子域都沿用本轮的标准：
+
+- 一次只切一个完整边界
+- 命令行为保持不变
+- 新模块必须有单测
+- 通过关键 integration 回归后才保留
+
+## 验证基线
+
+本轮用于验收的最低基线：
+
+- `npx jest tests/unit/auto --runInBand`
+- `npx jest tests/unit/commands/auto.test.js --runInBand`
+- `npx jest tests/integration/auto-close-loop-cli.integration.test.js tests/integration/version-cli.integration.test.js --runInBand`
+- `npm run test:release`
+
+下一轮建议继续沿用这套基线。
+
+## 发布状态
+
+当前稳定版本：
+
+- version: `3.6.33`
+- tag: `v3.6.33`
+
+后续 `auto-handoff` 的继续演进，应以这个版本作为新的稳定基线。

package/docs/zh/release-checklist.md

@@ -100,28 +100,35 @@ node scripts/git-managed-gate.js --fail-on-violation --json
 
 确认：
 
+- 发布自动化是基于 tag，而不是普通 commit：
+  - `.github/workflows/release.yml` 只在 `push.tags: v*` 时触发
+  - 普通 `git push` 只会跑常规 CI，不会发布 npm 包，也不会创建 GitHub Release
+- GitHub Actions 发版前置条件已配置：
+  - 仓库 Secret `NPM_TOKEN` 必须存在且有效，workflow 会用它执行 `npm publish --access public`
+  - workflow 的 release 资产/回读步骤依赖 `GITHUB_TOKEN`
 - `package.json` 版本号正确；
+- `package.json` 版本号必须大于 npm 当前已发布版本；
 - `CHANGELOG.md` 已记录发布相关变化；
 - 发布说明草稿已就绪（如 `docs/releases/vX.Y.Z.md`）。
 - 可选：通过仓库变量配置 release evidence 门禁（`Settings -> Secrets and variables -> Actions -> Variables`）：
-  - `KSE_RELEASE_GATE_ENFORCE`：`true|false`（默认 advisory，不阻断发布）
-  - `KSE_RELEASE_GATE_REQUIRE_EVIDENCE`：是否要求存在 `handoff-runs.json` 摘要
-  - `KSE_RELEASE_GATE_REQUIRE_GATE_PASS`：是否要求 evidence gate `passed=true`（有 evidence 时默认要求）
-  - `KSE_RELEASE_GATE_MIN_SPEC_SUCCESS_RATE`：最小允许成功率（百分比）
-  - `KSE_RELEASE_GATE_MAX_RISK_LEVEL`：`low|medium|high|unknown`（默认 `unknown`）
-  - `KSE_RELEASE_GATE_MAX_UNMAPPED_RULES`：ontology 业务规则未映射最大允许值
-  - `KSE_RELEASE_GATE_MAX_UNDECIDED_DECISIONS`：ontology 决策未定最大允许值
-  - `KSE_RELEASE_GATE_REQUIRE_SCENE_BATCH_PASS`：是否要求 scene package publish-batch gate 必须通过（`true|false`，默认 `true`）
-  - `KSE_RELEASE_GATE_MAX_SCENE_BATCH_FAILURES`：scene package batch 失败数量最大允许值（默认 `0`）
+  - `SCE_RELEASE_GATE_ENFORCE`：`true|false`（默认 advisory，不阻断发布）
+  - `SCE_RELEASE_GATE_REQUIRE_EVIDENCE`：是否要求存在 `handoff-runs.json` 摘要
+  - `SCE_RELEASE_GATE_REQUIRE_GATE_PASS`：是否要求 evidence gate `passed=true`（有 evidence 时默认要求）
+  - `SCE_RELEASE_GATE_MIN_SPEC_SUCCESS_RATE`：最小允许成功率（百分比）
+  - `SCE_RELEASE_GATE_MAX_RISK_LEVEL`：`low|medium|high|unknown`（默认 `unknown`）
+  - `SCE_RELEASE_GATE_MAX_UNMAPPED_RULES`：ontology 业务规则未映射最大允许值
+  - `SCE_RELEASE_GATE_MAX_UNDECIDED_DECISIONS`：ontology 决策未定最大允许值
+  - `SCE_RELEASE_GATE_REQUIRE_SCENE_BATCH_PASS`：是否要求 scene package publish-batch gate 必须通过（`true|false`，默认 `true`）
+  - `SCE_RELEASE_GATE_MAX_SCENE_BATCH_FAILURES`：scene package batch 失败数量最大允许值（默认 `0`）
 - 可选：通过仓库变量调节 Release Notes 中的漂移告警阈值：
   - CI 中漂移评估由 `scripts/release-drift-evaluate.js` 执行（历史读取、告警计算、gate 报告写回、enforce 退出码）。
-  - `KSE_RELEASE_DRIFT_ENFORCE`：`true|false`（默认 `false`），触发 drift alert 时阻断发布
-  - `KSE_RELEASE_DRIFT_FAIL_STREAK_MIN`：触发告警的最小连续失败次数（默认 `2`）
-  - `KSE_RELEASE_DRIFT_HIGH_RISK_SHARE_MIN_PERCENT`：近 5 版 high 风险占比告警阈值（默认 `60`）
-  - `KSE_RELEASE_DRIFT_HIGH_RISK_SHARE_DELTA_MIN_PERCENT`：短期相对长期 high 风险占比增量阈值（默认 `25`）
-  - `KSE_RELEASE_DRIFT_PREFLIGHT_BLOCK_RATE_MIN_PERCENT`：近 5 版（有 preflight 信号）blocked 占比告警阈值（默认 `40`）
-  - `KSE_RELEASE_DRIFT_HARD_GATE_BLOCK_STREAK_MIN`：hard-gate preflight 连续 blocked 告警阈值（最近窗口，默认 `2`）
-  - `KSE_RELEASE_DRIFT_PREFLIGHT_UNAVAILABLE_STREAK_MIN`：release preflight 连续 unavailable 告警阈值（最近窗口，默认 `2`）
+  - `SCE_RELEASE_DRIFT_ENFORCE`：`true|false`（默认 `false`），触发 drift alert 时阻断发布
+  - `SCE_RELEASE_DRIFT_FAIL_STREAK_MIN`：触发告警的最小连续失败次数（默认 `2`）
+  - `SCE_RELEASE_DRIFT_HIGH_RISK_SHARE_MIN_PERCENT`：近 5 版 high 风险占比告警阈值（默认 `60`）
+  - `SCE_RELEASE_DRIFT_HIGH_RISK_SHARE_DELTA_MIN_PERCENT`：短期相对长期 high 风险占比增量阈值（默认 `25`）
+  - `SCE_RELEASE_DRIFT_PREFLIGHT_BLOCK_RATE_MIN_PERCENT`：近 5 版（有 preflight 信号）blocked 占比告警阈值（默认 `40`）
+  - `SCE_RELEASE_DRIFT_HARD_GATE_BLOCK_STREAK_MIN`：hard-gate preflight 连续 blocked 告警阈值（最近窗口，默认 `2`）
+  - `SCE_RELEASE_DRIFT_PREFLIGHT_UNAVAILABLE_STREAK_MIN`：release preflight 连续 unavailable 告警阈值（最近窗口，默认 `2`）
 - 可选：发布资产 0 字节防护（workflow 默认开启）
   - `scripts/release-asset-nonempty-normalize.js` 会在上传 GitHub Release 资产前，为可选 `.lines` / `.jsonl` 资产自动补齐占位内容，避免 422。
   - 本地 dry-run 示例：
@@ -131,4 +138,20 @@ node scripts/git-managed-gate.js --fail-on-violation --json
 - 可选本地预演 release gate 历史索引产物：
   - `sce auto handoff gate-index --dir .sce/reports/release-evidence --out .sce/reports/release-evidence/release-gate-history.json --json`
 
-然后再执行你的正式发布流程（打 tag、push、npm publish、GitHub Release）。
+然后再执行正式发布流程：
+
+```bash
+# 1. 先升级版本并提交
+# 2. 先 push 分支代码
+git push origin main
+
+# 3. 再创建并 push 发版 tag
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+预期：
+
+- `git push origin main` 只跑常规 CI；
+- `git push origin vX.Y.Z` 才会触发 GitHub Actions `Release` workflow；
+- 只有 release workflow 全部门禁通过后，才会自动发布 npm 包并创建 GitHub Release。

package/docs/zh/releases/README.md

@@ -9,6 +9,7 @@
 ## 历史版本归档
 
 - [发布检查清单](../release-checklist.md)
+- [v3.6.37 发布说明](./v3.6.37.md)
 - [v1.46.2 发布说明](./v1.46.2.md)（历史归档）
 - [v1.46.2 验证报告](./v1.46.2-validation.md)（历史归档）
 - [GitHub Releases](https://github.com/heguangyong/scene-capability-engine/releases)（最新）

package/docs/zh/releases/v3.6.37.md

@@ -0,0 +1,22 @@
+# v3.6.37 发布说明
+
+发布日期：2026-03-12
+
+## 重点变化
+
+- 彻底移除了运行路径、模板、夹具和对外文档中的旧 `kse` 命令与内容，不再保留兼容桥接。
+- 将 scene package / template 元数据与 fixture 路径统一到 `sce` 命名，避免新产物继续泄漏旧 `kse` 标识。
+- 修复了 Windows 下 `scripts/git-managed-gate.js` 的 git 可执行文件解析问题，新增 `git.cmd` / `git.exe` 回退，避免发布前置门禁误判。
+- 明确记录了真实发布方式：只有 `v*` tag push 才会触发 GitHub Actions 发版，且 workflow 发布依赖仓库 Secret `NPM_TOKEN`。
+
+## 验证
+
+- `npx jest tests/unit/workspace/workspace-context-resolver.test.js tests/unit/workspace/workspace-state-manager.test.js tests/unit/steering/compliance-cache.test.js tests/unit/scripts/moqui-lexicon-audit.test.js tests/unit/scripts/moqui-standard-rebuild.test.js tests/unit/scripts/moqui-metadata-extract.test.js tests/unit/task/task-claimer.test.js tests/unit/commands/auto.test.js tests/integration/auto-close-loop-cli.integration.test.js --runInBand`
+- `node scripts/check-branding-consistency.js`
+- `npx jest tests/unit/scripts/git-managed-gate.test.js --runInBand`
+
+## 发布说明
+
+- 普通 `git push` 不会发布本项目。
+- 只有 `git push origin vX.Y.Z` 触发 `.github/workflows/release.yml` 后，才会进入自动发布流程。
+- GitHub Actions 发版依赖仓库 Secret `NPM_TOKEN`。

package/lib/app/registry-config.js

@@ -0,0 +1,73 @@
+const path = require('path');
+const fs = require('fs-extra');
+
+const DEFAULT_APP_REGISTRY_CONFIG_PATH = path.join('.sce', 'config', 'app-registries.json');
+
+const DEFAULT_APP_REGISTRY_CONFIG = Object.freeze({
+  version: '1.0',
+  bundle_registry: {
+    repo_url: 'https://github.com/heguangyong/magicball-app-bundle-registry.git',
+    branch: 'main',
+    index_url: 'https://raw.githubusercontent.com/heguangyong/magicball-app-bundle-registry/main/bundles/index.json'
+  },
+  service_catalog: {
+    repo_url: 'https://github.com/heguangyong/magicball-app-service-catalog.git',
+    branch: 'main',
+    index_url: 'https://raw.githubusercontent.com/heguangyong/magicball-app-service-catalog/main/catalog/index.json'
+  }
+});
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function mergeSection(base = {}, patch = {}) {
+  return {
+    ...base,
+    ...Object.fromEntries(
+      Object.entries(patch || {}).filter(([, value]) => value !== undefined)
+    )
+  };
+}
+
+async function loadAppRegistryConfig(projectPath = process.cwd(), fileSystem = fs) {
+  const configPath = path.join(projectPath, DEFAULT_APP_REGISTRY_CONFIG_PATH);
+  let filePayload = {};
+  if (await fileSystem.pathExists(configPath)) {
+    filePayload = await fileSystem.readJson(configPath);
+  }
+  return {
+    config_path: DEFAULT_APP_REGISTRY_CONFIG_PATH,
+    config: {
+      version: normalizeString(filePayload.version) || DEFAULT_APP_REGISTRY_CONFIG.version,
+      bundle_registry: mergeSection(DEFAULT_APP_REGISTRY_CONFIG.bundle_registry, filePayload.bundle_registry),
+      service_catalog: mergeSection(DEFAULT_APP_REGISTRY_CONFIG.service_catalog, filePayload.service_catalog)
+    }
+  };
+}
+
+async function saveAppRegistryConfig(patch = {}, projectPath = process.cwd(), fileSystem = fs) {
+  const loaded = await loadAppRegistryConfig(projectPath, fileSystem);
+  const nextConfig = {
+    version: DEFAULT_APP_REGISTRY_CONFIG.version,
+    bundle_registry: mergeSection(loaded.config.bundle_registry, patch.bundle_registry),
+    service_catalog: mergeSection(loaded.config.service_catalog, patch.service_catalog)
+  };
+  const configPath = path.join(projectPath, DEFAULT_APP_REGISTRY_CONFIG_PATH);
+  await fileSystem.ensureDir(path.dirname(configPath));
+  await fileSystem.writeJson(configPath, nextConfig, { spaces: 2 });
+  return {
+    config_path: DEFAULT_APP_REGISTRY_CONFIG_PATH,
+    config: nextConfig
+  };
+}
+
+module.exports = {
+  DEFAULT_APP_REGISTRY_CONFIG_PATH,
+  DEFAULT_APP_REGISTRY_CONFIG,
+  loadAppRegistryConfig,
+  saveAppRegistryConfig
+};

package/lib/app/registry-sync-service.js

@@ -0,0 +1,228 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { loadAppRegistryConfig } = require('./registry-config');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+async function readJsonResource(resourceRef, dependencies = {}) {
+  const fileSystem = dependencies.fileSystem || fs;
+  const fetchImpl = dependencies.fetchImpl || global.fetch;
+  const normalized = normalizeString(resourceRef);
+  if (!normalized) {
+    throw new Error('resource reference is required');
+  }
+  if (/^https?:\/\//i.test(normalized)) {
+    if (typeof fetchImpl !== 'function') {
+      throw new Error(`fetch unavailable for remote resource: ${normalized}`);
+    }
+    const response = await fetchImpl(normalized);
+    if (!response || response.ok !== true) {
+      const status = response && typeof response.status !== 'undefined' ? response.status : 'unknown';
+      throw new Error(`failed to fetch ${normalized} (status=${status})`);
+    }
+    return response.json();
+  }
+  const resolvedPath = path.isAbsolute(normalized)
+    ? normalized
+    : path.join(dependencies.projectPath || process.cwd(), normalized);
+  return fileSystem.readJson(resolvedPath);
+}
+
+function resolveChildResource(parentRef, childRef) {
+  const normalizedParent = normalizeString(parentRef);
+  const normalizedChild = normalizeString(childRef);
+  if (!normalizedChild) {
+    return normalizedParent;
+  }
+  if (/^https?:\/\//i.test(normalizedChild) || path.isAbsolute(normalizedChild)) {
+    return normalizedChild;
+  }
+  if (/^https?:\/\//i.test(normalizedParent)) {
+    return new URL(normalizedChild, normalizedParent).toString();
+  }
+  return path.join(path.dirname(normalizedParent), normalizedChild);
+}
+
+function graphToRegisterPayload(graph = {}) {
+  const bundle = graph.bundle || {};
+  const runtimeRelease = graph.runtime_release || {};
+  const ontologyBundle = graph.ontology_bundle || {};
+  const engineeringProject = graph.engineering_project || {};
+  return {
+    app_id: bundle.app_id,
+    app_key: bundle.app_key,
+    app_name: bundle.app_name,
+    app_slug: bundle.app_slug || undefined,
+    workspace_id: bundle.workspace_id || undefined,
+    runtime_release_id: bundle.runtime_release_id || undefined,
+    ontology_bundle_id: bundle.ontology_bundle_id || undefined,
+    engineering_project_id: bundle.engineering_project_id || undefined,
+    default_scene_id: bundle.default_scene_id || undefined,
+    environment: bundle.environment || undefined,
+    status: bundle.status || undefined,
+    source_origin: bundle.source_origin || undefined,
+    tags: Array.isArray(bundle.tags) ? bundle.tags : [],
+    metadata: bundle.metadata && typeof bundle.metadata === 'object' ? { ...bundle.metadata } : {},
+    runtime: runtimeRelease && runtimeRelease.release_id ? {
+      release_id: runtimeRelease.release_id,
+      runtime_version: runtimeRelease.runtime_version,
+      release_channel: runtimeRelease.release_channel,
+      release_status: runtimeRelease.release_status,
+      entrypoint: runtimeRelease.entrypoint,
+      runtime_status: runtimeRelease.runtime_status,
+      release_notes_file: runtimeRelease.release_notes_file,
+      release_evidence_file: runtimeRelease.release_evidence_file,
+      published_at: runtimeRelease.published_at,
+      source_updated_at: runtimeRelease.source_updated_at,
+      metadata: runtimeRelease.metadata || {}
+    } : undefined,
+    ontology: ontologyBundle && ontologyBundle.ontology_bundle_id ? {
+      ontology_bundle_id: ontologyBundle.ontology_bundle_id,
+      ontology_version: ontologyBundle.ontology_version,
+      template_version: ontologyBundle.template_version,
+      capability_catalog_version: ontologyBundle.capability_catalog_version,
+      triad_revision: ontologyBundle.triad_revision,
+      triad_status: ontologyBundle.triad_status,
+      publish_readiness: ontologyBundle.publish_readiness,
+      template_source: ontologyBundle.template_source,
+      capability_set: Array.isArray(ontologyBundle.capability_set) ? ontologyBundle.capability_set : [],
+      summary: ontologyBundle.summary || {},
+      metadata: ontologyBundle.metadata || {}
+    } : undefined,
+    engineering: engineeringProject && engineeringProject.engineering_project_id ? {
+      engineering_project_id: engineeringProject.engineering_project_id,
+      project_key: engineeringProject.project_key,
+      project_name: engineeringProject.project_name,
+      repo_url: engineeringProject.repo_url,
+      repo_provider: engineeringProject.repo_provider,
+      default_branch: engineeringProject.default_branch,
+      current_branch: engineeringProject.current_branch,
+      commit_sha: engineeringProject.commit_sha,
+      workspace_path: engineeringProject.workspace_path,
+      code_version: engineeringProject.code_version,
+      synced_runtime_release_id: engineeringProject.synced_runtime_release_id,
+      dirty_state: engineeringProject.dirty_state === true,
+      auth_policy: engineeringProject.auth_policy || {},
+      metadata: engineeringProject.metadata || {}
+    } : undefined,
+    scene_bindings: Array.isArray(graph.scene_bindings)
+      ? graph.scene_bindings.map((item) => ({
+        scene_id: item.scene_id,
+        binding_role: item.binding_role,
+        source: item.source,
+        metadata: item.metadata || {}
+      }))
+      : []
+  };
+}
+
+async function syncBundleRegistry(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateStore = dependencies.stateStore;
+  const loadedConfig = await loadAppRegistryConfig(projectPath, fileSystem);
+  const indexRef = normalizeString(options.indexUrl) || normalizeString(loadedConfig.config.bundle_registry.index_url);
+  const indexPayload = await readJsonResource(indexRef, dependencies);
+  const bundleItems = Array.isArray(indexPayload && indexPayload.bundles) ? indexPayload.bundles : [];
+  const synced = [];
+  for (const item of bundleItems) {
+    const resourceRef = normalizeString(item && item.url) || resolveChildResource(indexRef, item && item.file);
+    const bundlePayload = await readJsonResource(resourceRef, dependencies);
+    const graph = await stateStore.registerAppBundle(bundlePayload);
+    synced.push({
+      app_id: graph && graph.bundle ? graph.bundle.app_id : null,
+      app_key: graph && graph.bundle ? graph.bundle.app_key : null,
+      source: resourceRef
+    });
+  }
+  return {
+    mode: 'app-registry-sync-bundles',
+    index_url: indexRef,
+    source_generated_at: indexPayload && indexPayload.generated_at ? indexPayload.generated_at : null,
+    synced_count: synced.length,
+    items: synced
+  };
+}
+
+async function syncServiceCatalog(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const stateStore = dependencies.stateStore;
+  const loadedConfig = await loadAppRegistryConfig(projectPath, fileSystem);
+  const indexRef = normalizeString(options.indexUrl) || normalizeString(loadedConfig.config.service_catalog.index_url);
+  const indexPayload = await readJsonResource(indexRef, dependencies);
+  const appItems = Array.isArray(indexPayload && indexPayload.apps) ? indexPayload.apps : [];
+  const synced = [];
+  for (const item of appItems) {
+    const resourceRef = normalizeString(item && item.url) || resolveChildResource(indexRef, item && item.file);
+    const appPayload = await readJsonResource(resourceRef, dependencies);
+    const appId = normalizeString(appPayload && appPayload.app_id);
+    const appKey = normalizeString(appPayload && appPayload.app_key);
+    const appName = normalizeString(appPayload && appPayload.app_name);
+    let graph = await stateStore.getAppBundleGraph(appId || appKey);
+    if (!graph) {
+      graph = await stateStore.registerAppBundle({
+        app_id: appId,
+        app_key: appKey,
+        app_name: appName || appKey || appId,
+        status: 'active',
+        environment: normalizeString(appPayload && appPayload.environment) || null,
+        source_origin: 'app-service-catalog-sync'
+      });
+    }
+    const nextPayload = graphToRegisterPayload(graph);
+    const releases = Array.isArray(appPayload && appPayload.releases) ? appPayload.releases : [];
+    const defaultReleaseId = normalizeString(appPayload && appPayload.default_release_id) || (releases[0] && normalizeString(releases[0].release_id)) || null;
+    const activeRelease = releases.find((entry) => normalizeString(entry && entry.release_id) === defaultReleaseId) || releases[0] || null;
+    nextPayload.metadata = nextPayload.metadata || {};
+    nextPayload.metadata.service_catalog = {
+      synced_at: new Date().toISOString(),
+      source: resourceRef,
+      app_name: appName || null,
+      default_release_id: defaultReleaseId,
+      releases
+    };
+    if (activeRelease) {
+      nextPayload.runtime_release_id = normalizeString(activeRelease.release_id);
+      nextPayload.runtime = {
+        release_id: normalizeString(activeRelease.release_id),
+        runtime_version: normalizeString(activeRelease.runtime_version),
+        release_channel: normalizeString(activeRelease.release_channel) || null,
+        release_status: normalizeString(activeRelease.release_status) || 'published',
+        entrypoint: normalizeString(activeRelease.entrypoint) || null,
+        runtime_status: normalizeString(activeRelease.runtime_status) || null,
+        release_notes_file: normalizeString(activeRelease.release_notes_file) || null,
+        release_evidence_file: normalizeString(activeRelease.release_evidence_file) || null,
+        published_at: normalizeString(activeRelease.published_at) || null,
+        metadata: activeRelease.metadata && typeof activeRelease.metadata === 'object' ? activeRelease.metadata : {}
+      };
+    }
+    const updated = await stateStore.registerAppBundle(nextPayload);
+    synced.push({
+      app_id: updated && updated.bundle ? updated.bundle.app_id : appId,
+      app_key: updated && updated.bundle ? updated.bundle.app_key : appKey,
+      source: resourceRef,
+      release_count: releases.length,
+      default_release_id: defaultReleaseId || null
+    });
+  }
+  return {
+    mode: 'app-registry-sync-service-catalog',
+    index_url: indexRef,
+    source_generated_at: indexPayload && indexPayload.generated_at ? indexPayload.generated_at : null,
+    synced_count: synced.length,
+    items: synced
+  };
+}
+
+module.exports = {
+  readJsonResource,
+  resolveChildResource,
+  syncBundleRegistry,
+  syncServiceCatalog
+};