scene-capability-engine 3.3.22 → 3.3.23

package/docs/command-reference.md

@@ -351,6 +351,16 @@ sce errorbook record \
 sce errorbook list --status promoted --min-quality 75 --json
 sce errorbook show <entry-id> --json
 sce errorbook find --query "approve order timeout" --limit 10 --json
+sce errorbook find --query "approve order timeout" --include-registry --json
+# Prefer remote indexed search for large registry
+sce errorbook find --query "approve order timeout" --include-registry --registry-mode remote --json
+sce errorbook find --query "approve order timeout" --include-registry --registry-mode hybrid --json
+
+# Export curated local entries for central registry publication
+sce errorbook export --status promoted --min-quality 75 --out .sce/errorbook/exports/registry.json --json
+
+# Sync central registry (GitHub raw URL or local file) to local cache
+sce errorbook sync-registry --source https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json --json
 
 # Promote only after strict gate checks pass
 sce errorbook promote <entry-id> --json
@@ -400,6 +410,10 @@ Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
 - `release-gate` also blocks when temporary mitigation policy is violated:
   - missing exit/cleanup/deadline metadata
   - expired mitigation deadline
+- `export` outputs a machine-readable registry bundle from curated local entries (recommended default: `promoted`, `quality>=75`).
+- `sync-registry` pulls external registry JSON into local cache (`.sce/errorbook/registry-cache.json`) for unified `find` retrieval.
+- `find --include-registry --registry-mode remote` supports direct remote query for large registries (no full local sync required).
+- Recommended for large registries: maintain a remote index file (`registry/errorbook-registry.index.json`) and shard files, then provide `index_url` in registry config.
 - `git-managed-gate` blocks release when:
   - worktree has uncommitted changes
   - branch has no upstream
@@ -2036,6 +2050,7 @@ Overall Health: 2 healthy, 1 unhealthy
 - [Cross-Tool Guide](./cross-tool-guide.md)
 - [Adoption Guide](./adoption-guide.md)
 - [Developer Guide](./developer-guide.md)
+- [Errorbook Registry Guide](./errorbook-registry.md)
 
 ---
 

package/docs/errorbook-registry.md

@@ -0,0 +1,116 @@
+# Errorbook Registry Guide
+
+This guide defines how to run a shared, cross-project `errorbook` registry as a dedicated GitHub repository.
+
+## 1) Repository Scope
+
+- Repository role: shared curated failure/remediation knowledge.
+- Recommended repo name: `sce-errorbook-registry`.
+- Keep this repository independent from scene/spec template repositories.
+
+## 2) Recommended Repository Structure
+
+```text
+sce-errorbook-registry/
+  registry/
+    errorbook-registry.json
+  README.md
+```
+
+`registry/errorbook-registry.json` should follow:
+
+```json
+{
+  "api_version": "sce.errorbook.registry/v0.1",
+  "generated_at": "2026-02-27T00:00:00.000Z",
+  "source": {
+    "project": "curation-pipeline",
+    "statuses": ["promoted"],
+    "min_quality": 75
+  },
+  "total_entries": 0,
+  "entries": []
+}
+```
+
+For large registries, add an index + shard layout:
+
+```text
+registry/
+  errorbook-registry.index.json
+  shards/
+    order.json
+    payment.json
+    auth.json
+```
+
+Example `registry/errorbook-registry.index.json`:
+
+```json
+{
+  "api_version": "sce.errorbook.registry-index/v0.1",
+  "generated_at": "2026-02-27T00:00:00.000Z",
+  "min_token_length": 2,
+  "token_to_bucket": {
+    "order": "order",
+    "approve": "order",
+    "payment": "payment"
+  },
+  "buckets": {
+    "order": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/shards/order.json",
+    "payment": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/shards/payment.json"
+  }
+}
+```
+
+## 3) Project-Side Configuration
+
+Create `.sce/config/errorbook-registry.json`:
+
+```json
+{
+  "enabled": true,
+  "search_mode": "remote",
+  "cache_file": ".sce/errorbook/registry-cache.json",
+  "sources": [
+    {
+      "name": "central",
+      "enabled": true,
+      "url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json",
+      "index_url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.index.json"
+    }
+  ]
+}
+```
+
+Notes:
+- `url` must be a raw JSON URL (`raw.githubusercontent.com`) or use a local file path.
+- `search_mode` supports `cache|remote|hybrid` (recommended: `remote` for very large registries).
+- Local cache file is used by cache/hybrid mode.
+
+## 4) Daily Workflow
+
+1. Export curated local entries:
+```bash
+sce errorbook export --status promoted --min-quality 75 --out .sce/errorbook/exports/registry.json --json
+```
+
+2. Merge approved entries into central repo `registry/errorbook-registry.json`.
+
+3. Sync central registry into local cache:
+```bash
+sce errorbook sync-registry --source https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json --json
+```
+
+4. Search local + shared entries:
+```bash
+sce errorbook find --query "approve order timeout" --include-registry --json
+sce errorbook find --query "approve order timeout" --include-registry --registry-mode remote --json
+```
+
+## 5) Governance Rules
+
+- Publish to central registry only curated entries (recommended: `status=promoted` and `quality>=75`).
+- Do not publish sensitive tenant/customer data.
+- Temporary mitigation entries must remain bounded and governed (exit criteria, cleanup task, deadline).
+- Keep central registry append-only by PR review; deprecate low-value entries through normal curation.

package/lib/adoption/adoption-strategy.js

@@ -113,6 +113,8 @@ class AdoptionStrategy {
       'steering/CURRENT_CONTEXT.md',
       'steering/RULES_GUIDE.md',
       'config/studio-security.json',
+      'config/orchestrator.json',
+      'config/errorbook-registry.json',
       'specs/SPEC_WORKFLOW_GUIDE.md',
       'hooks/sync-tasks-on-edit.sce.hook',
       'hooks/check-spec-on-create.sce.hook',

package/lib/adoption/backup-manager.js

@@ -316,6 +316,8 @@ class BackupManager {
       'steering/CORE_PRINCIPLES.md',
       'steering/ENVIRONMENT.md',
       'config/studio-security.json',
+      'config/orchestrator.json',
+      'config/errorbook-registry.json',
       'version.json',
       'adoption-config.json'
     ];

package/lib/adoption/detection-engine.js

@@ -162,6 +162,8 @@ class DetectionEngine {
         'steering/RULES_GUIDE.md',
         'tools/ultrawork_enhancer.py',
         'config/studio-security.json',
+        'config/orchestrator.json',
+        'config/errorbook-registry.json',
         'README.md',
         'ultrawork-application-guide.md',
         'ultrawork-integration-summary.md',

package/lib/adoption/file-classifier.js

@@ -63,7 +63,9 @@ class FileClassifier {
     this.configPatterns = [
       'version.json',
       'adoption-config.json',
-      'config/studio-security.json'
+      'config/studio-security.json',
+      'config/orchestrator.json',
+      'config/errorbook-registry.json'
     ];
 
     // Generated directory patterns

package/lib/adoption/smart-orchestrator.js

@@ -283,6 +283,8 @@ class SmartOrchestrator {
       'steering/RULES_GUIDE.md',
       'tools/ultrawork_enhancer.py',
       'config/studio-security.json',
+      'config/orchestrator.json',
+      'config/errorbook-registry.json',
       'README.md'
     ];
 

package/lib/adoption/strategy-selector.js

@@ -110,6 +110,8 @@ class StrategySelector {
         'steering/RULES_GUIDE.md',
         'tools/ultrawork_enhancer.py',
         'config/studio-security.json',
+        'config/orchestrator.json',
+        'config/errorbook-registry.json',
         'README.md'
       ];
 

package/lib/adoption/template-sync.js

@@ -29,6 +29,8 @@ class TemplateSync {
       'steering/RULES_GUIDE.md',
       'tools/ultrawork_enhancer.py',
       'config/studio-security.json',
+      'config/orchestrator.json',
+      'config/errorbook-registry.json',
       'README.md',
       'ultrawork-application-guide.md',
       'ultrawork-integration-summary.md',

package/lib/commands/errorbook.js

@@ -1,4 +1,6 @@
 const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
 const path = require('path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
@@ -6,8 +8,14 @@ const Table = require('cli-table3');
 
 const ERRORBOOK_INDEX_API_VERSION = 'sce.errorbook.index/v0.1';
 const ERRORBOOK_ENTRY_API_VERSION = 'sce.errorbook.entry/v0.1';
+const ERRORBOOK_REGISTRY_API_VERSION = 'sce.errorbook.registry/v0.1';
+const ERRORBOOK_REGISTRY_CACHE_API_VERSION = 'sce.errorbook.registry-cache/v0.1';
+const ERRORBOOK_REGISTRY_INDEX_API_VERSION = 'sce.errorbook.registry-index/v0.1';
 const ERRORBOOK_STATUSES = Object.freeze(['candidate', 'verified', 'promoted', 'deprecated']);
 const TEMPORARY_MITIGATION_TAG = 'temporary-mitigation';
+const DEFAULT_ERRORBOOK_REGISTRY_CONFIG = '.sce/config/errorbook-registry.json';
+const DEFAULT_ERRORBOOK_REGISTRY_CACHE = '.sce/errorbook/registry-cache.json';
+const DEFAULT_ERRORBOOK_REGISTRY_EXPORT = '.sce/errorbook/exports/errorbook-registry-export.json';
 const STATUS_RANK = Object.freeze({
   deprecated: 0,
   candidate: 1,
@@ -60,6 +68,28 @@ function resolveErrorbookPaths(projectPath = process.cwd()) {
   };
 }
 
+function resolveProjectPath(projectPath, maybeRelativePath, fallbackRelativePath) {
+  const normalized = normalizeText(maybeRelativePath || fallbackRelativePath || '');
+  if (!normalized) {
+    return path.resolve(projectPath, fallbackRelativePath || '');
+  }
+  return path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+}
+
+function resolveErrorbookRegistryPaths(projectPath = process.cwd(), overrides = {}) {
+  const configFile = resolveProjectPath(projectPath, overrides.configPath, DEFAULT_ERRORBOOK_REGISTRY_CONFIG);
+  const cacheFile = resolveProjectPath(projectPath, overrides.cachePath, DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  const exportFile = resolveProjectPath(projectPath, overrides.exportPath, DEFAULT_ERRORBOOK_REGISTRY_EXPORT);
+  return {
+    projectPath,
+    configFile,
+    cacheFile,
+    exportFile
+  };
+}
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -589,6 +619,382 @@ async function loadRecordPayloadFromFile(projectPath, sourcePath, fileSystem = f
   }
 }
 
+function normalizeStatusList(values = [], fallback = ['promoted']) {
+  const raw = Array.isArray(values) ? values : normalizeStringList(values);
+  const list = raw.length > 0 ? raw : fallback;
+  const normalized = list
+    .map((item) => normalizeText(item).toLowerCase())
+    .filter(Boolean);
+  const unique = Array.from(new Set(normalized));
+  for (const status of unique) {
+    if (!ERRORBOOK_STATUSES.includes(status)) {
+      throw new Error(`invalid status in list: ${status}`);
+    }
+  }
+  return unique;
+}
+
+function normalizeRegistrySource(input = {}) {
+  const candidate = input || {};
+  const name = normalizeText(candidate.name) || 'default';
+  const url = normalizeText(candidate.url || candidate.source);
+  const file = normalizeText(candidate.file || candidate.path);
+  const source = url || file;
+  const indexUrl = normalizeText(candidate.index_url || candidate.indexUrl || candidate.registry_index || candidate.registryIndex);
+  return {
+    name,
+    source,
+    index_url: indexUrl,
+    enabled: candidate.enabled !== false
+  };
+}
+
+function normalizeRegistryMode(value, fallback = 'cache') {
+  const normalized = normalizeText(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['cache', 'remote', 'hybrid'].includes(normalized)) {
+    return normalized;
+  }
+  throw new Error('registry mode must be one of: cache, remote, hybrid');
+}
+
+async function readErrorbookRegistryConfig(paths, fileSystem = fs) {
+  const fallback = {
+    enabled: false,
+    search_mode: 'cache',
+    cache_file: DEFAULT_ERRORBOOK_REGISTRY_CACHE,
+    sources: []
+  };
+  if (!await fileSystem.pathExists(paths.configFile)) {
+    return fallback;
+  }
+  const payload = await fileSystem.readJson(paths.configFile).catch(() => null);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return fallback;
+  }
+  const sources = Array.isArray(payload.sources)
+    ? payload.sources.map((item) => normalizeRegistrySource(item)).filter((item) => item.enabled && item.source)
+    : [];
+  return {
+    enabled: normalizeBoolean(payload.enabled, true),
+    search_mode: normalizeRegistryMode(payload.search_mode || payload.searchMode, 'cache'),
+    cache_file: normalizeText(payload.cache_file || payload.cacheFile || DEFAULT_ERRORBOOK_REGISTRY_CACHE),
+    sources
+  };
+}
+
+function isHttpSource(source = '') {
+  return /^https?:\/\//i.test(normalizeText(source));
+}
+
+function fetchJsonFromHttp(source, timeoutMs = 15000) {
+  const normalized = normalizeText(source);
+  if (!normalized) {
+    return Promise.reject(new Error('registry source is required'));
+  }
+  const client = normalized.startsWith('https://') ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = client.get(normalized, {
+      timeout: timeoutMs,
+      headers: {
+        Accept: 'application/json'
+      }
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`registry source responded ${response.statusCode}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(new Error(`registry source returned invalid JSON: ${error.message}`));
+        }
+      });
+    });
+    request.on('timeout', () => {
+      request.destroy(new Error('registry source request timed out'));
+    });
+    request.on('error', reject);
+  });
+}
+
+async function loadRegistryPayload(projectPath, source, fileSystem = fs) {
+  const normalized = normalizeText(source);
+  if (!normalized) {
+    throw new Error('registry source is required');
+  }
+  if (isHttpSource(normalized)) {
+    return fetchJsonFromHttp(normalized);
+  }
+  const absolutePath = path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+  if (!await fileSystem.pathExists(absolutePath)) {
+    throw new Error(`registry source file not found: ${source}`);
+  }
+  return fileSystem.readJson(absolutePath);
+}
+
+function normalizeRegistryEntry(entry = {}, sourceName = 'registry') {
+  const title = normalizeText(entry.title || entry.name);
+  const symptom = normalizeText(entry.symptom);
+  const rootCause = normalizeText(entry.root_cause || entry.rootCause);
+  const fingerprint = createFingerprint({
+    fingerprint: normalizeText(entry.fingerprint),
+    title,
+    symptom,
+    root_cause: rootCause
+  });
+  const statusRaw = normalizeText(entry.status || 'candidate').toLowerCase();
+  const status = ERRORBOOK_STATUSES.includes(statusRaw) ? statusRaw : 'candidate';
+  const mitigation = normalizeExistingTemporaryMitigation(entry.temporary_mitigation);
+
+  return {
+    id: normalizeText(entry.id) || `registry-${fingerprint}`,
+    fingerprint,
+    title,
+    symptom,
+    root_cause: rootCause,
+    fix_actions: normalizeStringList(entry.fix_actions, entry.fixActions),
+    verification_evidence: normalizeStringList(entry.verification_evidence, entry.verificationEvidence),
+    tags: normalizeStringList(entry.tags, mitigation.enabled ? TEMPORARY_MITIGATION_TAG : []),
+    ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+    status,
+    quality_score: Number.isFinite(Number(entry.quality_score)) ? Number(entry.quality_score) : scoreQuality(entry),
+    updated_at: normalizeIsoTimestamp(entry.updated_at || entry.updatedAt, 'registry.updated_at') || nowIso(),
+    source: {
+      ...entry.source,
+      registry: sourceName
+    },
+    temporary_mitigation: mitigation,
+    entry_source: 'registry'
+  };
+}
+
+function extractRegistryEntries(payload = {}, sourceName = 'registry') {
+  const rawEntries = Array.isArray(payload)
+    ? payload
+    : Array.isArray(payload.entries)
+      ? payload.entries
+      : [];
+  const normalized = [];
+  for (const item of rawEntries) {
+    if (!item || typeof item !== 'object') {
+      continue;
+    }
+    const entry = normalizeRegistryEntry(item, sourceName);
+    if (!entry.title || !entry.fingerprint) {
+      continue;
+    }
+    normalized.push(entry);
+  }
+  const deduped = new Map();
+  for (const entry of normalized) {
+    const key = entry.fingerprint;
+    const existing = deduped.get(key);
+    if (!existing) {
+      deduped.set(key, entry);
+      continue;
+    }
+    if ((Number(entry.quality_score) || 0) >= (Number(existing.quality_score) || 0)) {
+      deduped.set(key, entry);
+    }
+  }
+  return Array.from(deduped.values());
+}
+
+async function loadRegistryCache(projectPath, cachePathInput = '', fileSystem = fs) {
+  const cachePath = resolveProjectPath(projectPath, cachePathInput, DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  if (!await fileSystem.pathExists(cachePath)) {
+    return {
+      cache_path: cachePath,
+      entries: []
+    };
+  }
+  const payload = await fileSystem.readJson(cachePath).catch(() => null);
+  const entries = extractRegistryEntries(payload || {}, 'registry-cache');
+  return {
+    cache_path: cachePath,
+    entries
+  };
+}
+
+function tokenizeQueryText(query = '') {
+  return normalizeText(query)
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/i)
+    .map((item) => item.trim())
+    .filter((item) => item.length >= 2);
+}
+
+function normalizeRegistryIndex(payload = {}, sourceName = '') {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null;
+  }
+  return {
+    api_version: normalizeText(payload.api_version || payload.version || ERRORBOOK_REGISTRY_INDEX_API_VERSION),
+    source_name: sourceName || normalizeText(payload.source_name || payload.sourceName),
+    min_token_length: Number.isFinite(Number(payload.min_token_length))
+      ? Number(payload.min_token_length)
+      : 2,
+    token_to_source: payload.token_to_source && typeof payload.token_to_source === 'object'
+      ? payload.token_to_source
+      : {},
+    token_to_bucket: payload.token_to_bucket && typeof payload.token_to_bucket === 'object'
+      ? payload.token_to_bucket
+      : {},
+    buckets: payload.buckets && typeof payload.buckets === 'object'
+      ? payload.buckets
+      : {},
+    default_source: normalizeText(payload.default_source || payload.fallback_source || '')
+  };
+}
+
+function collectRegistryShardSources(indexPayload, queryTokens = [], maxShards = 8) {
+  const index = normalizeRegistryIndex(indexPayload);
+  if (!index) {
+    return [];
+  }
+  const sources = [];
+  const minTokenLength = Number.isFinite(index.min_token_length) ? index.min_token_length : 2;
+  for (const token of queryTokens) {
+    const normalizedToken = normalizeText(token).toLowerCase();
+    if (!normalizedToken || normalizedToken.length < minTokenLength) {
+      continue;
+    }
+    const direct = index.token_to_source[normalizedToken];
+    if (direct) {
+      const items = Array.isArray(direct) ? direct : [direct];
+      for (const item of items) {
+        sources.push(normalizeText(item));
+      }
+      continue;
+    }
+    const bucket = normalizeText(index.token_to_bucket[normalizedToken]);
+    if (!bucket) {
+      continue;
+    }
+    const bucketSource = normalizeText(index.buckets[bucket] || index.buckets[normalizedToken]);
+    if (bucketSource) {
+      sources.push(bucketSource);
+    }
+  }
+
+  const deduped = Array.from(new Set(sources.filter(Boolean)));
+  if (deduped.length > 0) {
+    return Number.isFinite(Number(maxShards)) && Number(maxShards) > 0
+      ? deduped.slice(0, Number(maxShards))
+      : deduped;
+  }
+  if (index.default_source) {
+    return [index.default_source];
+  }
+  return [];
+}
+
+async function searchRegistryRemote(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const source = normalizeRegistrySource(options.source || {});
+  const query = normalizeText(options.query);
+  const queryTokens = Array.isArray(options.queryTokens) ? options.queryTokens : tokenizeQueryText(query);
+  const requestedStatus = options.requestedStatus || null;
+  const maxShards = Number.isFinite(Number(options.maxShards)) ? Number(options.maxShards) : 8;
+  const allowRemoteFullscan = options.allowRemoteFullscan === true;
+
+  if (!source.source) {
+    return {
+      source_name: source.name || 'registry',
+      shard_sources: [],
+      matched_count: 0,
+      candidates: [],
+      warnings: ['registry source is empty']
+    };
+  }
+
+  const warnings = [];
+  let shardSources = [];
+  if (source.index_url) {
+    try {
+      const indexPayload = await loadRegistryPayload(projectPath, source.index_url, fileSystem);
+      shardSources = collectRegistryShardSources(indexPayload, queryTokens, maxShards);
+    } catch (error) {
+      warnings.push(`failed to load registry index (${source.index_url}): ${error.message}`);
+    }
+  }
+
+  if (shardSources.length === 0) {
+    if (allowRemoteFullscan) {
+      shardSources = [source.source];
+      warnings.push('remote index unavailable; fallback to full-source scan');
+    } else {
+      warnings.push('remote index unavailable and full-source scan disabled');
+      return {
+        source_name: source.name || 'registry',
+        shard_sources: [],
+        matched_count: 0,
+        candidates: [],
+        warnings
+      };
+    }
+  }
+
+  const candidates = [];
+  for (const shardSource of shardSources) {
+    try {
+      const payload = await loadRegistryPayload(projectPath, shardSource, fileSystem);
+      const entries = extractRegistryEntries(payload, source.name || 'registry');
+      for (const entry of entries) {
+        if (requestedStatus && normalizeStatus(entry.status, 'candidate') !== requestedStatus) {
+          continue;
+        }
+        const matchScore = scoreSearchMatch(entry, queryTokens);
+        if (matchScore <= 0) {
+          continue;
+        }
+        candidates.push({
+          id: entry.id,
+          entry_source: 'registry-remote',
+          registry_source: source.name || 'registry',
+          status: entry.status,
+          quality_score: entry.quality_score,
+          title: entry.title,
+          fingerprint: entry.fingerprint,
+          tags: normalizeStringList(entry.tags),
+          ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+          match_score: matchScore,
+          updated_at: entry.updated_at
+        });
+      }
+    } catch (error) {
+      warnings.push(`failed to load registry shard (${shardSource}): ${error.message}`);
+    }
+  }
+
+  const deduped = new Map();
+  for (const item of candidates) {
+    const key = normalizeText(item.fingerprint || item.id);
+    const existing = deduped.get(key);
+    if (!existing || Number(item.match_score || 0) >= Number(existing.match_score || 0)) {
+      deduped.set(key, item);
+    }
+  }
+
+  return {
+    source_name: source.name || 'registry',
+    shard_sources: shardSources,
+    matched_count: deduped.size,
+    candidates: Array.from(deduped.values()),
+    warnings
+  };
+}
+
 function printRecordSummary(result) {
   const action = result.created ? 'Recorded new entry' : 'Updated duplicate fingerprint';
   console.log(chalk.green(`✓ ${action}`));
@@ -945,6 +1351,154 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
   return result;
 }
 
+async function runErrorbookExportCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const paths = resolveErrorbookPaths(projectPath);
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    exportPath: options.out
+  });
+  const index = await readErrorbookIndex(paths, fileSystem);
+
+  const statuses = normalizeStatusList(options.statuses || options.status || 'promoted', ['promoted']);
+  const minQuality = Number.isFinite(Number(options.minQuality))
+    ? Number(options.minQuality)
+    : 75;
+  const limit = Number.isFinite(Number(options.limit)) && Number(options.limit) > 0
+    ? Number(options.limit)
+    : 0;
+
+  const selected = [];
+  for (const summary of index.entries) {
+    const entry = await readErrorbookEntry(paths, summary.id, fileSystem);
+    if (!entry) {
+      continue;
+    }
+    const status = normalizeStatus(entry.status, 'candidate');
+    if (!statuses.includes(status)) {
+      continue;
+    }
+    if (Number(entry.quality_score || 0) < minQuality) {
+      continue;
+    }
+    selected.push({
+      id: entry.id,
+      fingerprint: entry.fingerprint,
+      title: entry.title,
+      symptom: entry.symptom,
+      root_cause: entry.root_cause,
+      fix_actions: normalizeStringList(entry.fix_actions),
+      verification_evidence: normalizeStringList(entry.verification_evidence),
+      tags: normalizeStringList(entry.tags),
+      ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+      status,
+      quality_score: Number(entry.quality_score || 0),
+      updated_at: entry.updated_at,
+      source: entry.source || {},
+      temporary_mitigation: normalizeExistingTemporaryMitigation(entry.temporary_mitigation)
+    });
+  }
+
+  selected.sort((left, right) => {
+    const qualityDiff = Number(right.quality_score || 0) - Number(left.quality_score || 0);
+    if (qualityDiff !== 0) {
+      return qualityDiff;
+    }
+    return `${right.updated_at || ''}`.localeCompare(`${left.updated_at || ''}`);
+  });
+
+  const entries = limit > 0 ? selected.slice(0, limit) : selected;
+  const payload = {
+    api_version: ERRORBOOK_REGISTRY_API_VERSION,
+    generated_at: nowIso(),
+    source: {
+      project: path.basename(projectPath),
+      statuses,
+      min_quality: minQuality
+    },
+    total_entries: entries.length,
+    entries
+  };
+
+  await fileSystem.ensureDir(path.dirname(registryPaths.exportFile));
+  await fileSystem.writeJson(registryPaths.exportFile, payload, { spaces: 2 });
+
+  const result = {
+    mode: 'errorbook-export',
+    out_file: registryPaths.exportFile,
+    statuses,
+    min_quality: minQuality,
+    total_entries: entries.length
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Exported curated errorbook entries'));
+    console.log(chalk.gray(`  out: ${registryPaths.exportFile}`));
+    console.log(chalk.gray(`  total: ${entries.length}`));
+    console.log(chalk.gray(`  statuses: ${statuses.join(', ')}`));
+  }
+
+  return result;
+}
+
+async function runErrorbookSyncRegistryCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    configPath: options.config,
+    cachePath: options.cache
+  });
+
+  const config = await readErrorbookRegistryConfig(registryPaths, fileSystem);
+  const sourceOption = normalizeText(options.source);
+  const configuredSource = config.sources.find((item) => item.enabled && item.source);
+  const source = sourceOption || (configuredSource ? configuredSource.source : '');
+  if (!source) {
+    throw new Error('registry source is required (use --source or configure .sce/config/errorbook-registry.json)');
+  }
+  const sourceName = normalizeText(options.sourceName)
+    || (configuredSource ? configuredSource.name : '')
+    || 'registry';
+
+  const payload = await loadRegistryPayload(projectPath, source, fileSystem);
+  const entries = extractRegistryEntries(payload, sourceName);
+  const cachePath = resolveProjectPath(projectPath, options.cache, config.cache_file || DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  const cachePayload = {
+    api_version: ERRORBOOK_REGISTRY_CACHE_API_VERSION,
+    synced_at: nowIso(),
+    source: {
+      name: sourceName,
+      uri: source
+    },
+    total_entries: entries.length,
+    entries
+  };
+
+  await fileSystem.ensureDir(path.dirname(cachePath));
+  await fileSystem.writeJson(cachePath, cachePayload, { spaces: 2 });
+
+  const result = {
+    mode: 'errorbook-sync-registry',
+    source,
+    source_name: sourceName,
+    cache_file: cachePath,
+    total_entries: entries.length
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Synced external errorbook registry'));
+    console.log(chalk.gray(`  source: ${source}`));
+    console.log(chalk.gray(`  cache: ${cachePath}`));
+    console.log(chalk.gray(`  entries: ${entries.length}`));
+  }
+
+  return result;
+}
+
 async function runErrorbookListCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -1071,9 +1625,15 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
   const limit = Number.isFinite(Number(options.limit)) && Number(options.limit) > 0
     ? Number(options.limit)
     : 10;
-  const tokens = query.toLowerCase().split(/[\s,;|]+/).map((item) => item.trim()).filter(Boolean);
+  const tokens = tokenizeQueryText(query);
+  const includeRegistry = options.includeRegistry === true;
 
   const candidates = [];
+  let localMatched = 0;
+  let registryMatched = 0;
+  let registryCacheMatched = 0;
+  let registryRemoteMatched = 0;
+  const registryWarnings = [];
   for (const summary of index.entries) {
     if (requestedStatus && summary.status !== requestedStatus) {
       continue;
@@ -1086,8 +1646,10 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
     if (matchScore <= 0) {
       continue;
     }
+    localMatched += 1;
     candidates.push({
       id: entry.id,
+      entry_source: 'local',
       status: entry.status,
       quality_score: entry.quality_score,
       title: entry.title,
@@ -1099,7 +1661,96 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
     });
   }
 
-  candidates.sort((left, right) => {
+  if (includeRegistry) {
+    const configPaths = resolveErrorbookRegistryPaths(projectPath, {
+      configPath: options.config,
+      cachePath: options.registryCache
+    });
+    const registryConfig = await readErrorbookRegistryConfig(configPaths, fileSystem);
+    const registryMode = normalizeRegistryMode(options.registryMode, registryConfig.search_mode || 'cache');
+    const useCache = registryMode === 'cache' || registryMode === 'hybrid';
+    const useRemote = registryMode === 'remote' || registryMode === 'hybrid';
+
+    if (useRemote) {
+      const configuredSources = Array.isArray(registryConfig.sources)
+        ? registryConfig.sources.filter((item) => item.enabled && item.source)
+        : [];
+      const overrideSource = normalizeText(options.registrySource);
+      const remoteSources = overrideSource
+        ? [normalizeRegistrySource({
+          name: normalizeText(options.registrySourceName) || 'override',
+          source: overrideSource,
+          index_url: normalizeText(options.registryIndex)
+        })]
+        : configuredSources;
+
+      for (const source of remoteSources) {
+        const remoteResult = await searchRegistryRemote({
+          source,
+          query,
+          queryTokens: tokens,
+          requestedStatus,
+          maxShards: options.registryMaxShards,
+          allowRemoteFullscan: options.allowRemoteFullscan === true
+        }, {
+          projectPath,
+          fileSystem
+        });
+        registryRemoteMatched += Number(remoteResult.matched_count || 0);
+        registryMatched += Number(remoteResult.matched_count || 0);
+        if (Array.isArray(remoteResult.warnings)) {
+          registryWarnings.push(...remoteResult.warnings);
+        }
+        if (Array.isArray(remoteResult.candidates)) {
+          candidates.push(...remoteResult.candidates);
+        }
+      }
+    }
+
+    if (useCache) {
+      const cachePath = resolveProjectPath(
+        projectPath,
+        options.registryCache,
+        registryConfig.cache_file || DEFAULT_ERRORBOOK_REGISTRY_CACHE
+      );
+      const registryCache = await loadRegistryCache(projectPath, cachePath, fileSystem);
+      for (const entry of registryCache.entries) {
+        if (requestedStatus && normalizeStatus(entry.status, 'candidate') !== requestedStatus) {
+          continue;
+        }
+        const matchScore = scoreSearchMatch(entry, tokens);
+        if (matchScore <= 0) {
+          continue;
+        }
+        registryMatched += 1;
+        registryCacheMatched += 1;
+        candidates.push({
+          id: entry.id,
+          entry_source: 'registry-cache',
+          status: entry.status,
+          quality_score: entry.quality_score,
+          title: entry.title,
+          fingerprint: entry.fingerprint,
+          tags: normalizeStringList(entry.tags),
+          ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+          match_score: matchScore,
+          updated_at: entry.updated_at
+        });
+      }
+    }
+  }
+
+  const dedupedCandidates = new Map();
+  for (const item of candidates) {
+    const key = normalizeText(item.fingerprint || item.id);
+    const existing = dedupedCandidates.get(key);
+    if (!existing || Number(item.match_score || 0) >= Number(existing.match_score || 0)) {
+      dedupedCandidates.set(key, item);
+    }
+  }
+  const sortedCandidates = Array.from(dedupedCandidates.values());
+
+  sortedCandidates.sort((left, right) => {
     const scoreDiff = Number(right.match_score) - Number(left.match_score);
     if (scoreDiff !== 0) {
       return scoreDiff;
@@ -1110,8 +1761,16 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
   const result = {
     mode: 'errorbook-find',
     query,
-    total_results: candidates.length,
-    entries: candidates.slice(0, limit)
+    include_registry: includeRegistry,
+    source_breakdown: {
+      local_results: localMatched,
+      registry_results: registryMatched,
+      registry_cache_results: registryCacheMatched,
+      registry_remote_results: registryRemoteMatched
+    },
+    warnings: normalizeStringList(registryWarnings),
+    total_results: sortedCandidates.length,
+    entries: sortedCandidates.slice(0, limit)
   };
 
   if (options.json) {
@@ -1439,6 +2098,15 @@ function registerErrorbookCommands(program) {
     .requiredOption('--query <text>', 'Search query')
     .option('--status <status>', `Filter by status (${ERRORBOOK_STATUSES.join(', ')})`)
     .option('--limit <n>', 'Maximum entries returned', parseInt, 10)
+    .option('--include-registry', 'Include external registry entries in search')
+    .option('--registry-mode <mode>', 'Registry lookup mode (cache|remote|hybrid)')
+    .option('--registry-source <url-or-path>', 'Override registry source (for remote mode)')
+    .option('--registry-source-name <name>', 'Override registry source label')
+    .option('--registry-index <url-or-path>', 'Override registry index source (for remote mode)')
+    .option('--registry-max-shards <n>', 'Max remote shards to fetch per query', parseInt, 8)
+    .option('--allow-remote-fullscan', 'Allow remote full-source fallback when index is unavailable')
+    .option('--registry-cache <path>', `Registry cache path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
     .option('--json', 'Emit machine-readable JSON')
     .action(async (options) => {
       try {
@@ -1448,6 +2116,38 @@ function registerErrorbookCommands(program) {
       }
     });
 
+  errorbook
+    .command('export')
+    .description('Export curated local entries for external registry publication')
+    .option('--status <csv>', 'Statuses to include (csv, default: promoted)', 'promoted')
+    .option('--min-quality <n>', 'Minimum quality score (default: 75)', parseInt)
+    .option('--limit <n>', 'Maximum entries exported', parseInt)
+    .option('--out <path>', `Output file (default: ${DEFAULT_ERRORBOOK_REGISTRY_EXPORT})`)
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookExportCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
+  errorbook
+    .command('sync-registry')
+    .description('Sync external errorbook registry to local cache')
+    .option('--source <url-or-path>', 'Registry source JSON (https://... or local file)')
+    .option('--source-name <name>', 'Registry source name label')
+    .option('--cache <path>', `Registry cache output path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookSyncRegistryCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
   errorbook
     .command('promote <id>')
     .description('Promote entry after strict quality gate')
@@ -1508,15 +2208,21 @@ module.exports = {
   ERRORBOOK_ONTOLOGY_TAGS,
   ERRORBOOK_RISK_LEVELS,
   TEMPORARY_MITIGATION_TAG,
+  DEFAULT_ERRORBOOK_REGISTRY_CONFIG,
+  DEFAULT_ERRORBOOK_REGISTRY_CACHE,
+  DEFAULT_ERRORBOOK_REGISTRY_EXPORT,
   HIGH_RISK_SIGNAL_TAGS,
   DEFAULT_PROMOTE_MIN_QUALITY,
   resolveErrorbookPaths,
+  resolveErrorbookRegistryPaths,
   normalizeOntologyTags,
   normalizeRecordPayload,
   scoreQuality,
   evaluateEntryRisk,
   evaluateErrorbookReleaseGate,
   runErrorbookRecordCommand,
+  runErrorbookExportCommand,
+  runErrorbookSyncRegistryCommand,
   runErrorbookListCommand,
   runErrorbookShowCommand,
   runErrorbookFindCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.22",
+  "version": "3.3.23",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {

package/template/.sce/config/errorbook-registry.json

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "search_mode": "remote",
+  "cache_file": ".sce/errorbook/registry-cache.json",
+  "sources": [
+    {
+      "name": "central",
+      "enabled": true,
+      "url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json",
+      "index_url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.index.json"
+    }
+  ]
+}