scene-capability-engine 3.3.23 → 3.3.25

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,

package/lib/commands/spec-bootstrap.js

@@ -11,6 +11,7 @@ const { ContextCollector } = require('../spec/bootstrap/context-collector');
 const { QuestionnaireEngine } = require('../spec/bootstrap/questionnaire-engine');
 const { DraftGenerator } = require('../spec/bootstrap/draft-generator');
 const { TraceEmitter } = require('../spec/bootstrap/trace-emitter');
+const { ensureSpecDomainArtifacts } = require('../spec/domain-modeling');
 const { SessionStore } = require('../runtime/session-store');
 const { resolveSpecSceneBinding } = require('../runtime/scene-session-binding');
 const { bindMultiSpecSceneSession } = require('../runtime/multi-spec-scene-session');
@@ -114,6 +115,14 @@ async function runSpecBootstrap(options = {}, dependencies = {}) {
       await fs.writeFile(files.tasks, draft.tasks, 'utf8');
     }
 
+    const domainArtifacts = await ensureSpecDomainArtifacts(projectPath, specName, {
+      dryRun: !!options.dryRun,
+      sceneId: sceneBinding.scene_id,
+      problemStatement: answers.problemStatement,
+      primaryFlow: answers.primaryFlow,
+      verificationPlan: answers.verificationPlan
+    });
+
     const result = {
       success: true,
       specName,
@@ -122,7 +131,10 @@ async function runSpecBootstrap(options = {}, dependencies = {}) {
       files: {
         requirements: path.relative(projectPath, files.requirements),
         design: path.relative(projectPath, files.design),
-        tasks: path.relative(projectPath, files.tasks)
+        tasks: path.relative(projectPath, files.tasks),
+        domain_map: path.relative(projectPath, domainArtifacts.paths.domain_map),
+        scene_spec: path.relative(projectPath, domainArtifacts.paths.scene_spec),
+        domain_chain: path.relative(projectPath, domainArtifacts.paths.domain_chain)
       },
       trace: {
         template: options.template || 'default',
@@ -141,7 +153,10 @@ async function runSpecBootstrap(options = {}, dependencies = {}) {
       preview: {
         requirements: draft.requirements,
         design: draft.design,
-        tasks: draft.tasks
+        tasks: draft.tasks,
+        domain_map: domainArtifacts.preview.domain_map,
+        scene_spec: domainArtifacts.preview.scene_spec,
+        domain_chain: domainArtifacts.preview.domain_chain
       },
       scene_session: sceneBinding
         ? {

package/lib/commands/spec-domain.js

@@ -0,0 +1,217 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const {
+  ensureSpecDomainArtifacts,
+  validateSpecDomainArtifacts
+} = require('../spec/domain-modeling');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function resolveSpecId(options = {}) {
+  return normalizeText(options.spec || options.name);
+}
+
+async function assertSpecExists(projectPath, specId, fileSystem = fs) {
+  const specPath = path.join(projectPath, '.sce', 'specs', specId);
+  if (!await fileSystem.pathExists(specPath)) {
+    throw new Error(`Spec not found: ${specId}`);
+  }
+  return specPath;
+}
+
+async function runSpecDomainInitCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = resolveSpecId(options);
+  if (!specId) {
+    throw new Error('--spec is required');
+  }
+  await assertSpecExists(projectPath, specId, fileSystem);
+
+  const result = await ensureSpecDomainArtifacts(projectPath, specId, {
+    fileSystem,
+    dryRun: options.dryRun === true,
+    force: false,
+    sceneId: options.scene,
+    problemStatement: options.problem,
+    primaryFlow: options.primaryFlow,
+    verificationPlan: options.verificationPlan
+  });
+
+  const payload = {
+    mode: 'spec-domain-init',
+    spec_id: specId,
+    dry_run: options.dryRun === true,
+    created: result.created,
+    files: result.paths
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Spec domain artifacts initialized'));
+    console.log(chalk.gray(`  spec: ${specId}`));
+  }
+
+  return payload;
+}
+
+async function runSpecDomainRefreshCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = resolveSpecId(options);
+  if (!specId) {
+    throw new Error('--spec is required');
+  }
+  await assertSpecExists(projectPath, specId, fileSystem);
+
+  const result = await ensureSpecDomainArtifacts(projectPath, specId, {
+    fileSystem,
+    dryRun: options.dryRun === true,
+    force: true,
+    sceneId: options.scene,
+    problemStatement: options.problem,
+    primaryFlow: options.primaryFlow,
+    verificationPlan: options.verificationPlan
+  });
+
+  const payload = {
+    mode: 'spec-domain-refresh',
+    spec_id: specId,
+    dry_run: options.dryRun === true,
+    refreshed: result.created,
+    files: result.paths
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Spec domain artifacts refreshed'));
+    console.log(chalk.gray(`  spec: ${specId}`));
+  }
+
+  return payload;
+}
+
+async function runSpecDomainValidateCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const specId = resolveSpecId(options);
+  if (!specId) {
+    throw new Error('--spec is required');
+  }
+  await assertSpecExists(projectPath, specId, fileSystem);
+
+  const validation = await validateSpecDomainArtifacts(projectPath, specId, fileSystem);
+  const payload = {
+    mode: 'spec-domain-validate',
+    spec_id: specId,
+    passed: validation.passed,
+    ratio: validation.ratio,
+    details: validation.details,
+    warnings: validation.warnings
+  };
+
+  if (options.failOnError && !validation.passed) {
+    throw new Error(`spec domain validation failed: ${validation.warnings.join('; ')}`);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else if (!options.silent) {
+    if (validation.passed) {
+      console.log(chalk.green('✓ Spec domain validation passed'));
+    } else {
+      console.log(chalk.red('✗ Spec domain validation failed'));
+      validation.warnings.forEach((message) => {
+        console.log(chalk.gray(`  - ${message}`));
+      });
+    }
+  }
+
+  return payload;
+}
+
+function registerSpecDomainCommand(program) {
+  const specDomain = program
+    .command('spec-domain')
+    .description('Manage problem-domain modeling artifacts (use: sce spec domain)');
+
+  specDomain
+    .command('init')
+    .description('Create missing problem-domain artifacts for a Spec')
+    .requiredOption('--spec <name>', 'Spec identifier')
+    .option('--scene <scene-id>', 'Scene id used in generated chain/model')
+    .option('--problem <text>', 'Problem statement seed')
+    .option('--primary-flow <text>', 'Primary flow seed')
+    .option('--verification-plan <text>', 'Verification plan seed')
+    .option('--dry-run', 'Preview output without writing files')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecDomainInitCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-domain init failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  specDomain
+    .command('refresh')
+    .description('Force-refresh problem-domain artifacts for a Spec')
+    .requiredOption('--spec <name>', 'Spec identifier')
+    .option('--scene <scene-id>', 'Scene id used in generated chain/model')
+    .option('--problem <text>', 'Problem statement seed')
+    .option('--primary-flow <text>', 'Primary flow seed')
+    .option('--verification-plan <text>', 'Verification plan seed')
+    .option('--dry-run', 'Preview output without writing files')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecDomainRefreshCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-domain refresh failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  specDomain
+    .command('validate')
+    .description('Validate problem-domain artifacts for a Spec')
+    .requiredOption('--spec <name>', 'Spec identifier')
+    .option('--fail-on-error', 'Exit non-zero when validation fails')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecDomainValidateCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-domain validate failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  runSpecDomainInitCommand,
+  runSpecDomainRefreshCommand,
+  runSpecDomainValidateCommand,
+  registerSpecDomainCommand
+};

package/lib/commands/spec-related.js

@@ -0,0 +1,70 @@
+const chalk = require('chalk');
+const { findRelatedSpecs } = require('../spec/related-specs');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+async function runSpecRelatedCommand(options = {}, dependencies = {}) {
+  const query = normalizeText(options.query);
+  const sceneId = normalizeText(options.scene);
+  const specId = normalizeText(options.spec);
+
+  if (!query && !sceneId && !specId) {
+    throw new Error('At least one selector is required: --query or --scene or --spec');
+  }
+
+  const payload = await findRelatedSpecs({
+    query,
+    sceneId,
+    sourceSpecId: specId,
+    limit: options.limit
+  }, dependencies);
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Related Specs'));
+    console.log(`  Query: ${payload.query || '(none)'}`);
+    console.log(`  Scene: ${payload.scene_id || '(none)'}`);
+    console.log(`  Source Spec: ${payload.source_spec_id || '(none)'}`);
+    console.log(`  Candidates: ${payload.total_candidates}`);
+    for (const item of payload.related_specs) {
+      console.log(`  - ${item.spec_id} | score=${item.score} | scene=${item.scene_id || 'n/a'}`);
+    }
+  }
+
+  return payload;
+}
+
+function registerSpecRelatedCommand(program) {
+  program
+    .command('spec-related')
+    .description('Find previously related Specs by query/scene context')
+    .option('--query <text>', 'Problem statement or search query')
+    .option('--scene <scene-id>', 'Scene id for scene-aligned lookup')
+    .option('--spec <spec-id>', 'Use existing spec as query seed')
+    .option('--limit <n>', 'Maximum related specs to return', '5')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecRelatedCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-related failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  runSpecRelatedCommand,
+  registerSpecRelatedCommand
+};
+