scene-capability-engine 3.3.24 → 3.3.25

package/CHANGELOG.md

@@ -42,6 +42,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - 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
+- Added historical related-spec retrieval for faster new-problem analysis:
+  - new command: `sce spec-related` (alias route: `sce spec related`)
+  - supports query/scene/spec-seeded lookup and relevance ranking
+  - `sce studio plan` now auto-loads related historical specs into job metadata (`source.related_specs`)
 
 ## [3.3.23] - 2026-02-27
 

package/bin/scene-capability-engine.js

@@ -20,6 +20,7 @@ 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 { registerSpecRelatedCommand } = require('../lib/commands/spec-related');
 const { registerValueCommands } = require('../lib/commands/value');
 const VersionChecker = require('../lib/version/version-checker');
 const {
@@ -57,6 +58,7 @@ const program = new Command();
  * - `sce spec pipeline ...` -> `sce spec-pipeline ...`
  * - `sce spec gate ...` -> `sce spec-gate ...`
  * - `sce spec domain ...` -> `sce spec-domain ...`
+ * - `sce spec related ...` -> `sce spec-related ...`
  * - `sce spec create <name> ...` -> `sce create-spec <name> ...`
  * - `sce spec <name> ...` -> `sce create-spec <name> ...` (legacy)
  *
@@ -96,6 +98,11 @@ function normalizeSpecCommandArgs(argv) {
     return normalized;
   }
 
+  if (commandToken === 'related') {
+    normalized.splice(commandIndex, 2, 'spec-related');
+    return normalized;
+  }
+
   if (commandToken === 'create') {
     normalized.splice(commandIndex, 2, 'create-spec');
     return normalized;
@@ -342,6 +349,9 @@ registerSpecGateCommand(program);
 // Spec domain modeling command
 registerSpecDomainCommand(program);
 
+// Spec related lookup command
+registerSpecRelatedCommand(program);
+
 // 系统诊断命令
 program
   .command('doctor')

package/docs/command-reference.md

@@ -73,6 +73,10 @@ sce spec domain init --spec 01-00-feature-name --scene scene.customer-order-inve
 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
 
+# Find related historical specs before starting a new analysis
+sce spec related --query "customer order inventory reconciliation drift" --scene scene.customer-order-inventory --json
+sce spec related --spec 01-00-feature-name --limit 8 --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
@@ -491,6 +495,7 @@ 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
+- `plan` auto-searches related historical specs by `scene + goal` and writes top candidates into job metadata (`source.related_specs`)
 - 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`)

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
+};
+

package/lib/commands/studio.js

@@ -8,6 +8,7 @@ const {
   DOMAIN_CHAIN_RELATIVE_PATH,
   ensureSpecDomainArtifacts
 } = require('../spec/domain-modeling');
+const { findRelatedSpecs } = require('../spec/related-specs');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -986,6 +987,25 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     projectPath,
     fileSystem
   });
+  const relatedSpecLookup = await findRelatedSpecs({
+    query: normalizeString(options.goal),
+    sceneId,
+    limit: 8,
+    excludeSpecId: domainChainBinding.spec_id || specId || null
+  }, {
+    projectPath,
+    fileSystem
+  });
+  const relatedSpecItems = Array.isArray(relatedSpecLookup.related_specs)
+    ? relatedSpecLookup.related_specs.map((item) => ({
+      spec_id: item.spec_id,
+      scene_id: item.scene_id || null,
+      score: Number(item.score || 0),
+      reasons: Array.isArray(item.reasons) ? item.reasons : [],
+      matched_tokens: Array.isArray(item.matched_tokens) ? item.matched_tokens : [],
+      updated_at: item.updated_at || null
+    }))
+    : [];
 
   const paths = resolveStudioPaths(projectPath);
   await ensureStudioDirectories(paths, fileSystem);
@@ -1013,7 +1033,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       domain_chain_spec_id: domainChainBinding.spec_id || null,
       domain_chain_path: domainChainBinding.chain_path || null,
       domain_chain_summary: domainChainBinding.summary || null,
-      domain_chain_reason: domainChainBinding.reason || null
+      domain_chain_reason: domainChainBinding.reason || null,
+      related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+      related_specs_top: relatedSpecItems
     }
   };
 
@@ -1040,11 +1062,18 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
         summary: domainChainBinding.summary || null,
         context: domainChainBinding.context || null,
         updated_at: domainChainBinding.updated_at || null
+      },
+      related_specs: {
+        query: relatedSpecLookup.query || '',
+        scene_id: relatedSpecLookup.scene_id || null,
+        total_candidates: Number(relatedSpecLookup.total_candidates || 0),
+        items: relatedSpecItems
       }
     },
     scene: {
       id: sceneId,
-      spec_id: domainChainBinding.spec_id || specId || null
+      spec_id: domainChainBinding.spec_id || specId || null,
+      related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
     },
     session: {
       policy: 'mandatory.scene-primary',
@@ -1073,7 +1102,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     domain_chain_resolved: domainChainBinding.resolved === true,
     domain_chain_source: domainChainBinding.source || 'none',
     domain_chain_spec_id: domainChainBinding.spec_id || null,
-    domain_chain_path: domainChainBinding.chain_path || null
+    domain_chain_path: domainChainBinding.chain_path || null,
+    related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+    related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 

package/lib/spec/related-specs.js

@@ -0,0 +1,260 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { DOMAIN_CHAIN_RELATIVE_PATH } = require('./domain-modeling');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function clampPositiveInteger(value, fallback, max = 100) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return Math.min(parsed, max);
+}
+
+function tokenizeText(value) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    return [];
+  }
+  return Array.from(new Set(
+    normalized
+      .split(/[^a-z0-9\u4e00-\u9fff]+/i)
+      .map((item) => item.trim())
+      .filter((item) => item.length >= 2 || /[\u4e00-\u9fff]/.test(item))
+  ));
+}
+
+function extractSceneIdFromSceneSpec(markdown) {
+  const content = normalizeText(markdown);
+  if (!content) {
+    return null;
+  }
+  const match = content.match(/Scene ID:\s*`([^`]+)`/i);
+  if (!match || !match[1]) {
+    return null;
+  }
+  return match[1].trim() || null;
+}
+
+async function safeReadJson(filePath, fileSystem = fs) {
+  if (!await fileSystem.pathExists(filePath)) {
+    return null;
+  }
+  try {
+    return await fileSystem.readJson(filePath);
+  } catch (_error) {
+    return null;
+  }
+}
+
+async function safeReadFile(filePath, fileSystem = fs) {
+  if (!await fileSystem.pathExists(filePath)) {
+    return '';
+  }
+  try {
+    return await fileSystem.readFile(filePath, 'utf8');
+  } catch (_error) {
+    return '';
+  }
+}
+
+async function resolveSpecSearchEntries(projectPath, fileSystem = fs) {
+  const specsRoot = path.join(projectPath, '.sce', 'specs');
+  if (!await fileSystem.pathExists(specsRoot)) {
+    return [];
+  }
+
+  const names = await fileSystem.readdir(specsRoot);
+  const entries = [];
+
+  for (const specId of names) {
+    const specRoot = path.join(specsRoot, specId);
+    let stat = null;
+    try {
+      stat = await fileSystem.stat(specRoot);
+    } catch (_error) {
+      continue;
+    }
+    if (!stat || !stat.isDirectory()) {
+      continue;
+    }
+
+    const domainChainPath = path.join(specRoot, DOMAIN_CHAIN_RELATIVE_PATH);
+    const sceneSpecPath = path.join(specRoot, 'custom', 'scene-spec.md');
+    const domainMapPath = path.join(specRoot, 'custom', 'problem-domain-map.md');
+    const requirementsPath = path.join(specRoot, 'requirements.md');
+    const designPath = path.join(specRoot, 'design.md');
+
+    const [
+      domainChain,
+      sceneSpecContent,
+      domainMapContent,
+      requirementsContent,
+      designContent
+    ] = await Promise.all([
+      safeReadJson(domainChainPath, fileSystem),
+      safeReadFile(sceneSpecPath, fileSystem),
+      safeReadFile(domainMapPath, fileSystem),
+      safeReadFile(requirementsPath, fileSystem),
+      safeReadFile(designPath, fileSystem)
+    ]);
+
+    const sceneId = normalizeText(
+      (domainChain && domainChain.scene_id) || extractSceneIdFromSceneSpec(sceneSpecContent) || ''
+    ) || null;
+    const problemStatement = normalizeText(
+      (domainChain && domainChain.problem && domainChain.problem.statement) || ''
+    ) || null;
+
+    const ontologyText = domainChain && domainChain.ontology
+      ? [
+        ...(Array.isArray(domainChain.ontology.entity) ? domainChain.ontology.entity : []),
+        ...(Array.isArray(domainChain.ontology.relation) ? domainChain.ontology.relation : []),
+        ...(Array.isArray(domainChain.ontology.business_rule) ? domainChain.ontology.business_rule : []),
+        ...(Array.isArray(domainChain.ontology.decision_policy) ? domainChain.ontology.decision_policy : []),
+        ...(Array.isArray(domainChain.ontology.execution_flow) ? domainChain.ontology.execution_flow : [])
+      ].join(' ')
+      : '';
+
+    const searchableText = [
+      specId,
+      sceneId || '',
+      problemStatement || '',
+      ontologyText,
+      sceneSpecContent.slice(0, 4000),
+      domainMapContent.slice(0, 3000),
+      requirementsContent.slice(0, 3000),
+      designContent.slice(0, 3000)
+    ].join('\n');
+
+    entries.push({
+      spec_id: specId,
+      scene_id: sceneId,
+      problem_statement: problemStatement,
+      updated_at: stat.mtime ? stat.mtime.toISOString() : null,
+      searchable_text: searchableText.toLowerCase()
+    });
+  }
+
+  return entries;
+}
+
+function calculateSpecRelevance(entry, queryTokens = [], sceneId = '') {
+  let score = 0;
+  const reasons = [];
+  const matchedTokens = [];
+  const normalizedSceneId = normalizeText(sceneId).toLowerCase();
+  const entrySceneId = normalizeText(entry.scene_id).toLowerCase();
+  const haystack = entry.searchable_text || '';
+
+  if (normalizedSceneId && entrySceneId) {
+    if (entrySceneId === normalizedSceneId) {
+      score += 90;
+      reasons.push('scene_exact');
+    } else if (entrySceneId.includes(normalizedSceneId) || normalizedSceneId.includes(entrySceneId)) {
+      score += 35;
+      reasons.push('scene_partial');
+    }
+  }
+
+  for (const token of queryTokens) {
+    if (!token || token.length < 2) {
+      continue;
+    }
+    if (haystack.includes(token)) {
+      score += 9;
+      matchedTokens.push(token);
+    }
+  }
+
+  if (matchedTokens.length > 0) {
+    reasons.push('query_overlap');
+  }
+
+  return {
+    score,
+    reasons,
+    matched_tokens: Array.from(new Set(matchedTokens)).slice(0, 20)
+  };
+}
+
+async function buildDerivedQueryFromSpec(projectPath, specId, fileSystem = fs) {
+  const specs = await resolveSpecSearchEntries(projectPath, fileSystem);
+  const selected = specs.find((item) => item.spec_id === specId);
+  if (!selected) {
+    return '';
+  }
+  return [
+    selected.problem_statement || '',
+    selected.scene_id || '',
+    selected.spec_id || ''
+  ].join(' ').trim();
+}
+
+async function findRelatedSpecs(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const limit = clampPositiveInteger(options.limit, 5, 50);
+  const sceneId = normalizeText(options.sceneId || options.scene);
+  const excludeSpecId = normalizeText(options.excludeSpecId);
+  const sourceSpecId = normalizeText(options.sourceSpecId || options.spec);
+
+  let query = normalizeText(options.query);
+  if (!query && sourceSpecId) {
+    query = await buildDerivedQueryFromSpec(projectPath, sourceSpecId, fileSystem);
+  }
+
+  const queryTokens = tokenizeText(query);
+  const entries = await resolveSpecSearchEntries(projectPath, fileSystem);
+  const ranked = [];
+
+  for (const entry of entries) {
+    if (excludeSpecId && entry.spec_id === excludeSpecId) {
+      continue;
+    }
+    const relevance = calculateSpecRelevance(entry, queryTokens, sceneId);
+    if (relevance.score <= 0) {
+      continue;
+    }
+    ranked.push({
+      spec_id: entry.spec_id,
+      scene_id: entry.scene_id,
+      problem_statement: entry.problem_statement,
+      updated_at: entry.updated_at,
+      score: relevance.score,
+      reasons: relevance.reasons,
+      matched_tokens: relevance.matched_tokens
+    });
+  }
+
+  ranked.sort((left, right) => {
+    if (right.score !== left.score) {
+      return right.score - left.score;
+    }
+    return String(right.updated_at || '').localeCompare(String(left.updated_at || ''));
+  });
+
+  return {
+    mode: 'spec-related',
+    success: true,
+    query: query || '',
+    scene_id: sceneId || null,
+    source_spec_id: sourceSpecId || null,
+    total_candidates: ranked.length,
+    related_specs: ranked.slice(0, limit)
+  };
+}
+
+module.exports = {
+  tokenizeText,
+  resolveSpecSearchEntries,
+  calculateSpecRelevance,
+  findRelatedSpecs
+};
+

package/package.json

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