scene-capability-engine 3.3.23 → 3.3.24

package/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- Errorbook registry health command for centralized registry governance:
+  - `sce errorbook health-registry`
+  - validates registry config readability, source/index reachability, and index bucket-to-shard resolution
+- New script gate:
+  - `node scripts/errorbook-registry-health-gate.js`
+  - supports strict mode via `SCE_REGISTRY_HEALTH_STRICT=1`
+
+### Changed
+- `prepublishOnly` now runs `gate:errorbook-registry-health` in advisory mode before `errorbook-release` gate.
+- Autonomous execution defaults are now hard-set to autonomous progression:
+  - `lib/auto/config-schema.js` default mode changed to `aggressive`
+  - default checkpoints now skip phase/final review pauses (`phaseCompletion=false`, `finalReview=false`)
+  - default safety confirmations for production/external/destructive are disabled in autonomous mode baseline
+  - `sce auto run/create` CLI defaults now use `--mode aggressive`
+- Steering hard rule strengthened: when the same issue fails target validation for 2 consecutive fix rounds, the 3rd round must switch to debug-log-driven diagnosis first (no blind patching without evidence).
+- `errorbook record` now enforces the same policy operationally:
+  - from the 3rd repeated record attempt of the same fingerprint, debug evidence becomes mandatory
+  - accepted signals include `--verification "debug: ..."`, `debug-evidence` tag, or debug trace/log references
+- Spec workflow now enforces domain-first scene modeling:
+  - `spec bootstrap` auto-generates mandatory artifacts:
+    - `.sce/specs/<spec>/custom/problem-domain-map.md`
+    - `.sce/specs/<spec>/custom/scene-spec.md`
+    - `.sce/specs/<spec>/custom/problem-domain-chain.json`
+  - `spec gate` hard-fail rule `domain_scene_modeling` now validates both markdown structure and machine-readable chain payload:
+    - `problem/ontology/hypotheses/risks/decision_execution_path/correction_loop/verification`
+- Added explicit domain modeling command set (also available via `sce spec domain ...` route):
+  - `sce spec-domain init --spec <id>`
+  - `sce spec-domain validate --spec <id> [--fail-on-error]`
+  - `sce spec-domain refresh --spec <id>`
+- Studio plan/generate now consume domain modeling context for correction guidance:
+  - `sce studio plan` supports `--spec <id>` to ingest `.sce/specs/<spec>/custom/problem-domain-chain.json` deterministically
+  - when `--spec` is omitted, `plan` auto-selects the latest scene-matching chain (`scene_id`)
+  - `sce studio generate` writes chain-aware metadata and `generate` stage report at `.sce/reports/studio/generate-<job-id>.json`
+  - `sce studio verify` / `sce studio release` now include domain-chain metadata in reports and pass `spec_id` into auto errorbook failure capture
+
+## [3.3.23] - 2026-02-27
+
+### Added
+- Adoption/default template coverage now includes central registry and orchestrator configs across init/adopt/upgrade flows:
+  - `.sce/config/errorbook-registry.json`
+  - `.sce/config/orchestrator.json`
+- Adoption config classification and backup critical-file handling now include:
+  - `config/errorbook-registry.json`
+  - `config/orchestrator.json`
+
+### Changed
+- Errorbook registry template defaults are now enabled out of the box:
+  - `enabled: true`
+  - `sources[central].enabled: true`
+- Central registry defaults point to the official shared registry:
+  - `https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json`
+  - `https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.index.json`
+
 ## [3.3.22] - 2026-02-27
 
 ### Added

package/bin/scene-capability-engine.js

@@ -19,6 +19,7 @@ const { registerSteeringCommands } = require('../lib/commands/steering');
 const { registerSpecBootstrapCommand } = require('../lib/commands/spec-bootstrap');
 const { registerSpecPipelineCommand } = require('../lib/commands/spec-pipeline');
 const { registerSpecGateCommand } = require('../lib/commands/spec-gate');
+const { registerSpecDomainCommand } = require('../lib/commands/spec-domain');
 const { registerValueCommands } = require('../lib/commands/value');
 const VersionChecker = require('../lib/version/version-checker');
 const {
@@ -55,6 +56,7 @@ const program = new Command();
  * - `sce spec bootstrap ...` -> `sce spec-bootstrap ...`
  * - `sce spec pipeline ...` -> `sce spec-pipeline ...`
  * - `sce spec gate ...` -> `sce spec-gate ...`
+ * - `sce spec domain ...` -> `sce spec-domain ...`
  * - `sce spec create <name> ...` -> `sce create-spec <name> ...`
  * - `sce spec <name> ...` -> `sce create-spec <name> ...` (legacy)
  *
@@ -89,6 +91,11 @@ function normalizeSpecCommandArgs(argv) {
     return normalized;
   }
 
+  if (commandToken === 'domain') {
+    normalized.splice(commandIndex, 2, 'spec-domain');
+    return normalized;
+  }
+
   if (commandToken === 'create') {
     normalized.splice(commandIndex, 2, 'create-spec');
     return normalized;
@@ -332,6 +339,9 @@ registerSpecPipelineCommand(program);
 // Spec gate command
 registerSpecGateCommand(program);
 
+// Spec domain modeling command
+registerSpecDomainCommand(program);
+
 // 系统诊断命令
 program
   .command('doctor')

package/docs/adoption-guide.md

@@ -562,8 +562,16 @@ your-project/
 │   │   ├── ENVIRONMENT.md
 │   │   ├── CURRENT_CONTEXT.md
 │   │   └── RULES_GUIDE.md
+│   ├── config/                     # Runtime/adoption baseline configs
+│   │   ├── studio-security.json
+│   │   ├── orchestrator.json
+│   │   └── errorbook-registry.json
 │   ├── tools/                      # Ultrawork tools
 │   │   └── ultrawork_enhancer.py
+│   ├── hooks/                      # Default hooks
+│   │   ├── check-spec-on-create.sce.hook
+│   │   ├── run-tests-on-save.sce.hook
+│   │   └── sync-tasks-on-edit.sce.hook
 │   ├── backups/                    # Automatic backups
 │   │   └── adopt-{timestamp}/
 │   └── README.md

package/docs/autonomous-control-guide.md

@@ -433,7 +433,7 @@ sce auto stop
 
 ## Execution Modes
 
-### Conservative Mode (Default)
+### Conservative Mode
 
 **Best for**: Production features, critical systems, first-time users
 
@@ -479,7 +479,7 @@ sce auto stop
 }
 ```
 
-### Aggressive Mode
+### Aggressive Mode (Default)
 
 **Best for**: Rapid prototyping, experimental features, experienced users
 
@@ -511,13 +511,13 @@ Location: `.sce/auto/config.json`
 ```json
 {
   "version": "1.0.0",
-  "mode": "balanced",
+  "mode": "aggressive",
   "checkpoints": {
     "requirementsReview": false,
     "designReview": false,
     "tasksReview": false,
-    "phaseCompletion": true,
-    "finalReview": true,
+    "phaseCompletion": false,
+    "finalReview": false,
     "errorThreshold": 3
   },
   "errorRecovery": {
@@ -527,9 +527,9 @@ Location: `.sce/auto/config.json`
     "learningEnabled": true
   },
   "safety": {
-    "requireProductionConfirmation": true,
-    "requireExternalResourceConfirmation": true,
-    "requireDestructiveOperationConfirmation": true,
+    "requireProductionConfirmation": false,
+    "requireExternalResourceConfirmation": false,
+    "requireDestructiveOperationConfirmation": false,
     "allowedOperations": [],
     "blockedOperations": []
   },

package/docs/command-reference.md

@@ -2,8 +2,8 @@
 
 > Quick reference for all `sce` commands
 
-**Version**: 2.0.0
-**Last Updated**: 2026-02-26
+**Version**: 3.3.23
+**Last Updated**: 2026-02-27
 
 ---
 
@@ -57,6 +57,10 @@ sce create-spec 01-00-feature-name
 
 # Bootstrap full Spec draft (requirements/design/tasks)
 sce spec bootstrap --name 01-00-feature-name --scene scene.customer-order-inventory --non-interactive
+# Bootstrap now also generates mandatory scene artifacts:
+# - .sce/specs/<spec>/custom/problem-domain-map.md
+# - .sce/specs/<spec>/custom/scene-spec.md
+# - .sce/specs/<spec>/custom/problem-domain-chain.json (machine-readable chain model)
 
 # Run pipeline for one Spec
 sce spec pipeline run --spec 01-00-feature-name --scene scene.customer-order-inventory
@@ -64,6 +68,11 @@ sce spec pipeline run --spec 01-00-feature-name --scene scene.customer-order-inv
 # Run gate for one Spec
 sce spec gate run --spec 01-00-feature-name --scene scene.customer-order-inventory --json
 
+# Maintain domain modeling artifacts explicitly
+sce spec domain init --spec 01-00-feature-name --scene scene.customer-order-inventory --json
+sce spec domain validate --spec 01-00-feature-name --fail-on-error --json
+sce spec domain refresh --spec 01-00-feature-name --scene scene.customer-order-inventory --json
+
 # Multi-Spec mode defaults to orchestrate routing
 sce spec bootstrap --specs "spec-a,spec-b" --max-parallel 3
 sce spec pipeline run --specs "spec-a,spec-b" --max-parallel 3
@@ -77,6 +86,11 @@ Spec session governance:
 - `spec bootstrap|pipeline run|gate run` must bind to an active scene primary session (`--scene <scene-id>` or implicit binding from latest/unique active scene).
 - When multiple active scenes exist, you must pass `--scene` explicitly.
 - Multi-Spec orchestrate fallback (`--specs ...`) follows the same scene binding and writes per-spec child-session archive records.
+- `spec bootstrap` always generates problem-domain and scene-spec artifacts to force domain-first exploration.
+- `spec gate` now hard-fails when either of the following is missing or structurally incomplete:
+  - `.sce/specs/<spec>/custom/problem-domain-map.md`
+  - `.sce/specs/<spec>/custom/scene-spec.md`
+  - `.sce/specs/<spec>/custom/problem-domain-chain.json`
 
 ### Value Metrics
 
@@ -362,6 +376,9 @@ sce errorbook export --status promoted --min-quality 75 --out .sce/errorbook/exp
 # 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
 
+# Validate registry config/source/index health
+sce errorbook health-registry --json
+
 # Promote only after strict gate checks pass
 sce errorbook promote <entry-id> --json
 
@@ -389,11 +406,17 @@ sce errorbook release-gate --min-risk high --fail-on-block --json
 
 # Git managed hard gate (default in prepublish and studio release preflight)
 node scripts/git-managed-gate.js --fail-on-violation --json
+
+# Registry health gate (advisory by default; strict when env enabled)
+node scripts/errorbook-registry-health-gate.js --json
+SCE_REGISTRY_HEALTH_STRICT=1 node scripts/errorbook-registry-health-gate.js --json
 ```
 
 Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
 - `record` requires: `title`, `symptom`, `root_cause`, and at least one `fix_action`.
 - Fingerprint dedup is automatic; repeated records merge evidence and increment occurrence count.
+- Repeated-failure hard rule: from attempt `#3` of the same fingerprint (two failed rounds already happened), record must include debug evidence.
+  Recommended forms: `--verification "debug: ..."` or tag `debug-evidence` or debug trace/log file references.
 - `promote` enforces strict gate:
   - `root_cause` present
   - `fix_actions` non-empty
@@ -414,6 +437,10 @@ Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
 - `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.
+- Since `v3.3.23`, `sce init` / `sce adopt` default baseline includes enabled central registry config in `.sce/config/errorbook-registry.json`.
+- `health-registry` validates config readability, source/index accessibility, and index-to-shard resolution before release.
+- `gate:errorbook-registry-health` runs in advisory mode by default during `prepublishOnly`.
+  Set `SCE_REGISTRY_HEALTH_STRICT=1` to fail release when registry health reports errors.
 - `git-managed-gate` blocks release when:
   - worktree has uncommitted changes
   - branch has no upstream
@@ -428,6 +455,8 @@ Curated quality policy (`宁缺毋滥，优胜略汰`) defaults:
 ```bash
 # Build a plan from chat/session context (scene is mandatory and becomes the primary session anchor)
 sce studio plan --scene scene.customer-order-inventory --from-chat session-20260226 --goal "customer+order+inventory demo" --json
+# Recommended: bind spec explicitly so Studio can ingest problem-domain-chain deterministically
+sce studio plan --scene scene.customer-order-inventory --spec 01-00-customer-order-inventory --from-chat session-20260226 --goal "customer+order+inventory demo" --json
 
 # Generate patch bundle metadata (scene is inherited from plan)
 sce studio generate --target 331 --json
@@ -460,11 +489,15 @@ SCE_STUDIO_REQUIRE_AUTH=1 SCE_STUDIO_AUTH_PASSWORD=top-secret sce studio apply -
 
 Stage guardrails are enforced by default:
 - `plan` requires `--scene`; SCE binds one active primary session per scene
+- `plan --spec <id>` (recommended) ingests `.sce/specs/<spec>/custom/problem-domain-chain.json` into studio job context
+- when `--spec` is omitted, `plan` auto-resolves the latest matching spec chain by `scene_id` when available
 - successful `release` auto-archives current scene session and auto-opens the next scene cycle session
 - `generate` requires `plan`
+- `generate` consumes the plan-stage domain-chain context and writes chain-aware metadata/report (`.sce/reports/studio/generate-<job-id>.json`)
 - `apply` requires `generate`
 - `verify` requires `apply`
 - `release` requires `verify`
+- `verify` / `release` reports and failure auto-records inherit `spec_id + domain-chain` context for better root-cause traceability
 
 Studio gate execution defaults:
 - `verify --profile standard` runs executable gates (unit test script when available, interactive governance report when present, scene package publish-batch dry-run when handoff manifest exists)
@@ -544,6 +577,7 @@ Multi-agent merge governance default:
 ```bash
 # One-command close-loop execution:
 # goal -> auto master/sub decomposition -> collab metadata -> orchestration -> terminal result
+# default behavior is enforced autonomous progression (no per-step confirmation pauses)
 sce auto close-loop "build autonomous close-loop and master/sub orchestration"
 # default sub-spec count is auto-selected by goal complexity (typically 3-5)
 

package/docs/errorbook-registry.md

@@ -87,6 +87,7 @@ 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.
+- Since `v3.3.23`, `sce init` / `sce adopt` template baselines include this config by default (central source enabled).
 
 ## 4) Daily Workflow
 
@@ -106,6 +107,11 @@ sce errorbook sync-registry --source https://raw.githubusercontent.com/heguangyo
 ```bash
 sce errorbook find --query "approve order timeout" --include-registry --json
 sce errorbook find --query "approve order timeout" --include-registry --registry-mode remote --json
+
+# Validate central registry health (config/source/index/shard)
+sce errorbook health-registry --json
+# Optional strict gate in CI/release
+SCE_REGISTRY_HEALTH_STRICT=1 node scripts/errorbook-registry-health-gate.js --json
 ```
 
 ## 5) Governance Rules
@@ -114,3 +120,9 @@ sce errorbook find --query "approve order timeout" --include-registry --registry
 - 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.
+- Recommended central repo gates:
+  - `node scripts/validate-registry.js`
+  - `node scripts/check-index-coverage.js --min-coverage 85`
+- Recommended project-side release gates:
+  - `npm run gate:errorbook-registry-health` (advisory default)
+  - `SCE_REGISTRY_HEALTH_STRICT=1 npm run gate:errorbook-registry-health` (strict)

package/lib/auto/config-schema.js

@@ -5,14 +5,14 @@
 
 const DEFAULT_CONFIG = {
   version: '1.0.0',
-  mode: 'balanced',
+  mode: 'aggressive',
   
   checkpoints: {
     requirementsReview: false,
     designReview: false,
     tasksReview: false,
-    phaseCompletion: true,
-    finalReview: true,
+    phaseCompletion: false,
+    finalReview: false,
     errorThreshold: 5
   },
   
@@ -24,9 +24,9 @@ const DEFAULT_CONFIG = {
   },
   
   safety: {
-    requireProductionConfirmation: true,
-    requireExternalResourceConfirmation: true,
-    requireDestructiveOperationConfirmation: true,
+    requireProductionConfirmation: false,
+    requireExternalResourceConfirmation: false,
+    requireDestructiveOperationConfirmation: false,
     allowedOperations: [],
     blockedOperations: []
   },
@@ -74,7 +74,7 @@ const MODE_PRESETS = {
       designReview: false,
       tasksReview: false,
       phaseCompletion: false,
-      finalReview: true,
+      finalReview: false,
       errorThreshold: 10
     }
   }

package/lib/commands/auto.js

@@ -104,7 +104,7 @@ function registerAutoCommands(program) {
   auto
     .command('run <spec-name>')
     .description('Run Spec autonomously')
-    .option('-m, --mode <mode>', 'Execution mode (conservative|balanced|aggressive)', 'balanced')
+    .option('-m, --mode <mode>', 'Execution mode (conservative|balanced|aggressive)', 'aggressive')
     .action(async (specName, options) => {
       try {
         console.log(chalk.blue(`Starting autonomous execution: ${specName}`));
@@ -133,7 +133,7 @@ function registerAutoCommands(program) {
     .command('create <feature-description>')
     .description('Create and run Spec autonomously')
     .option('-n, --name <name>', 'Spec name')
-    .option('-m, --mode <mode>', 'Execution mode', 'balanced')
+    .option('-m, --mode <mode>', 'Execution mode', 'aggressive')
     .action(async (description, options) => {
       try {
         const specName = options.name || generateSpecName(description);

package/lib/commands/errorbook.js

@@ -47,6 +47,11 @@ const ONTOLOGY_TAG_ALIASES = Object.freeze({
 });
 const DEFAULT_PROMOTE_MIN_QUALITY = 75;
 const ERRORBOOK_RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
+const DEBUG_EVIDENCE_TAGS = Object.freeze([
+  'debug-evidence',
+  'diagnostic-evidence',
+  'debug-log'
+]);
 const HIGH_RISK_SIGNAL_TAGS = Object.freeze([
   'release-blocker',
   'security',
@@ -481,6 +486,44 @@ function validateRecordPayload(payload) {
   }
 }
 
+function hasDebugEvidenceSignals(entry = {}) {
+  const tags = normalizeStringList(entry.tags).map((item) => item.toLowerCase());
+  if (tags.some((tag) => DEBUG_EVIDENCE_TAGS.includes(tag))) {
+    return true;
+  }
+
+  const verificationEvidence = normalizeStringList(entry.verification_evidence);
+  if (verificationEvidence.some((item) => /^debug:/i.test(item))) {
+    return true;
+  }
+
+  const sourceFiles = normalizeStringList(entry?.source?.files);
+  if (sourceFiles.some((item) => /(^|[\\/._-])(debug|trace|diagnostic|observability|telemetry|stack)/i.test(item))) {
+    return true;
+  }
+
+  const notes = normalizeText(entry.notes).toLowerCase();
+  if (notes && /(debug|trace|diagnostic|observability|telemetry|stack|日志|埋点|观测)/i.test(notes)) {
+    return true;
+  }
+
+  return false;
+}
+
+function enforceDebugEvidenceAfterRepeatedFailures(entry = {}, options = {}) {
+  const attemptCount = Number(options.attemptCount || 0);
+  if (!Number.isFinite(attemptCount) || attemptCount < 3) {
+    return;
+  }
+  if (hasDebugEvidenceSignals(entry)) {
+    return;
+  }
+  throw new Error(
+    'two failed fix rounds detected (attempt #3+): debug evidence is required. '
+    + 'Provide --verification "debug: ...", add tag debug-evidence, or include debug trace/log file references.'
+  );
+}
+
 function normalizeRecordPayload(options = {}, fromFilePayload = {}) {
   const temporaryMitigation = normalizeTemporaryMitigation(options, fromFilePayload);
   const payload = {
@@ -1287,6 +1330,9 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
       throw new Error(`errorbook index references missing entry: ${existingSummary.id}`);
     }
     entry = mergeEntry(existingEntry, normalized);
+    enforceDebugEvidenceAfterRepeatedFailures(entry, {
+      attemptCount: Number(entry.occurrences || 0)
+    });
     deduplicated = true;
   } else {
     const temporaryMitigation = normalizeExistingTemporaryMitigation(normalized.temporary_mitigation);
@@ -1499,6 +1545,196 @@ async function runErrorbookSyncRegistryCommand(options = {}, dependencies = {})
   return result;
 }
 
+async function runErrorbookRegistryHealthCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    configPath: options.config,
+    cachePath: options.cache
+  });
+
+  const warnings = [];
+  const errors = [];
+  const overrideSource = normalizeText(options.source);
+  const overrideIndex = normalizeText(options.index || options.registryIndex);
+  const overrideSourceName = normalizeText(options.sourceName || options.registrySourceName) || 'override';
+
+  const configExists = await fileSystem.pathExists(registryPaths.configFile);
+  if (configExists) {
+    try {
+      const rawConfig = await fileSystem.readJson(registryPaths.configFile);
+      if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+        errors.push(`registry config must be a JSON object: ${registryPaths.configFile}`);
+      }
+    } catch (error) {
+      errors.push(`failed to parse registry config (${registryPaths.configFile}): ${error.message}`);
+    }
+  } else if (!overrideSource) {
+    errors.push(`registry config file not found: ${registryPaths.configFile}`);
+  }
+
+  const config = await readErrorbookRegistryConfig(registryPaths, fileSystem);
+  let registryEnabled = normalizeBoolean(config.enabled, true);
+  let sources = Array.isArray(config.sources) ? config.sources : [];
+
+  if (overrideSource) {
+    registryEnabled = true;
+    sources = [normalizeRegistrySource({
+      name: overrideSourceName,
+      source: overrideSource,
+      index_url: overrideIndex
+    })];
+  } else if (overrideIndex && sources.length > 0) {
+    sources = sources.map((source, sourceIndex) => (
+      sourceIndex === 0 ? { ...source, index_url: overrideIndex } : source
+    ));
+  }
+
+  if (!registryEnabled) {
+    warnings.push('registry config is disabled');
+  }
+  if (registryEnabled && sources.length === 0) {
+    errors.push('registry enabled but no sources configured');
+  }
+
+  const maxShards = Number.isFinite(Number(options.maxShards)) && Number(options.maxShards) > 0
+    ? Number(options.maxShards)
+    : 8;
+  const shardSample = Number.isFinite(Number(options.shardSample)) && Number(options.shardSample) > 0
+    ? Number(options.shardSample)
+    : 2;
+
+  const sourceResults = [];
+  for (const source of sources) {
+    const sourceName = normalizeText(source.name) || 'registry';
+    const sourceReport = {
+      source_name: sourceName,
+      source: normalizeText(source.source),
+      index_url: normalizeText(source.index_url),
+      source_ok: false,
+      index_ok: null,
+      shard_sources_checked: 0,
+      source_entries: 0,
+      shard_entries: 0,
+      warnings: [],
+      errors: []
+    };
+
+    if (!sourceReport.source) {
+      sourceReport.errors.push('source is empty');
+    } else {
+      try {
+        const payload = await loadRegistryPayload(projectPath, sourceReport.source, fileSystem);
+        const entries = extractRegistryEntries(payload, sourceName);
+        sourceReport.source_ok = true;
+        sourceReport.source_entries = entries.length;
+        if (entries.length === 0) {
+          sourceReport.warnings.push('source returned no valid entries');
+        }
+      } catch (error) {
+        sourceReport.errors.push(`failed to load source (${sourceReport.source}): ${error.message}`);
+      }
+    }
+
+    if (!sourceReport.index_url) {
+      sourceReport.warnings.push('index_url not configured; remote indexed lookup health is partially validated');
+    } else {
+      try {
+        const indexPayload = await loadRegistryPayload(projectPath, sourceReport.index_url, fileSystem);
+        const index = normalizeRegistryIndex(indexPayload, sourceName);
+        if (!index) {
+          sourceReport.errors.push(`invalid index payload: ${sourceReport.index_url}`);
+        } else {
+          sourceReport.index_ok = true;
+          const tokenToBucket = index.token_to_bucket || {};
+          const unresolved = [];
+          for (const [token, bucketRaw] of Object.entries(tokenToBucket)) {
+            const bucket = normalizeText(bucketRaw);
+            if (!bucket) {
+              continue;
+            }
+            const bucketSource = normalizeText(index.buckets[bucket] || index.buckets[token]);
+            if (!bucketSource) {
+              unresolved.push(`${token}->${bucket}`);
+            }
+          }
+          if (unresolved.length > 0) {
+            sourceReport.errors.push(`unresolved index bucket mappings: ${unresolved.slice(0, 10).join(', ')}`);
+          }
+
+          const sampleTokens = Object.keys(tokenToBucket).slice(0, 64);
+          const shardSources = collectRegistryShardSources(index, sampleTokens, maxShards);
+          sourceReport.shard_sources_checked = shardSources.length;
+          if (shardSources.length === 0) {
+            sourceReport.warnings.push('index resolved zero shard sources');
+          }
+
+          for (const shardSource of shardSources.slice(0, shardSample)) {
+            try {
+              const shardPayload = await loadRegistryPayload(projectPath, shardSource, fileSystem);
+              const shardEntries = extractRegistryEntries(shardPayload, `${sourceName}-shard`);
+              sourceReport.shard_entries += shardEntries.length;
+            } catch (error) {
+              sourceReport.errors.push(`failed to load shard (${shardSource}): ${error.message}`);
+            }
+          }
+        }
+      } catch (error) {
+        sourceReport.index_ok = false;
+        sourceReport.errors.push(`failed to load index (${sourceReport.index_url}): ${error.message}`);
+      }
+    }
+
+    for (const message of sourceReport.warnings) {
+      warnings.push(`[${sourceName}] ${message}`);
+    }
+    for (const message of sourceReport.errors) {
+      errors.push(`[${sourceName}] ${message}`);
+    }
+    sourceResults.push(sourceReport);
+  }
+
+  const result = {
+    mode: 'errorbook-health-registry',
+    checked_at: nowIso(),
+    passed: errors.length === 0,
+    warning_count: warnings.length,
+    error_count: errors.length,
+    paths: {
+      config_file: registryPaths.configFile,
+      cache_file: registryPaths.cacheFile
+    },
+    config: {
+      exists: configExists,
+      enabled: registryEnabled,
+      search_mode: config.search_mode || 'cache',
+      source_count: sources.length
+    },
+    sources: sourceResults,
+    warnings,
+    errors
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    if (result.passed) {
+      console.log(chalk.green('✓ Errorbook registry health check passed'));
+    } else {
+      console.log(chalk.red('✗ Errorbook registry health check failed'));
+    }
+    console.log(chalk.gray(`  sources: ${result.config.source_count}`));
+    console.log(chalk.gray(`  warnings: ${result.warning_count}`));
+    console.log(chalk.gray(`  errors: ${result.error_count}`));
+  }
+
+  if (options.failOnAlert && !result.passed) {
+    throw new Error(`errorbook registry health failed: ${result.error_count} error(s)`);
+  }
+
+  return result;
+}
+
 async function runErrorbookListCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -2148,6 +2384,26 @@ function registerErrorbookCommands(program) {
       }
     });
 
+  errorbook
+    .command('health-registry')
+    .description('Validate external registry config/source/index health')
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
+    .option('--cache <path>', `Registry cache path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--source <url-or-path>', 'Override registry source JSON (https://... or local file)')
+    .option('--source-name <name>', 'Override source name label')
+    .option('--index <url-or-path>', 'Override registry index source (https://... or local file)')
+    .option('--max-shards <n>', 'Max index-resolved shards to validate', parseInt, 8)
+    .option('--shard-sample <n>', 'Shard sample count to fetch and validate', parseInt, 2)
+    .option('--fail-on-alert', 'Exit with error when health check finds errors')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookRegistryHealthCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
   errorbook
     .command('promote <id>')
     .description('Promote entry after strict quality gate')
@@ -2212,6 +2468,7 @@ module.exports = {
   DEFAULT_ERRORBOOK_REGISTRY_CACHE,
   DEFAULT_ERRORBOOK_REGISTRY_EXPORT,
   HIGH_RISK_SIGNAL_TAGS,
+  DEBUG_EVIDENCE_TAGS,
   DEFAULT_PROMOTE_MIN_QUALITY,
   resolveErrorbookPaths,
   resolveErrorbookRegistryPaths,
@@ -2223,6 +2480,7 @@ module.exports = {
   runErrorbookRecordCommand,
   runErrorbookExportCommand,
   runErrorbookSyncRegistryCommand,
+  runErrorbookRegistryHealthCommand,
   runErrorbookListCommand,
   runErrorbookShowCommand,
   runErrorbookFindCommand,