scene-capability-engine 3.3.26 → 3.4.5

package/lib/spec/domain-modeling.js

@@ -5,6 +5,17 @@ const DOMAIN_MAP_RELATIVE_PATH = path.join('custom', 'problem-domain-map.md');
 const SCENE_SPEC_RELATIVE_PATH = path.join('custom', 'scene-spec.md');
 const DOMAIN_CHAIN_RELATIVE_PATH = path.join('custom', 'problem-domain-chain.json');
 const DOMAIN_CHAIN_API_VERSION = 'sce.problem-domain-chain/v0.1';
+const DOMAIN_RESEARCH_DIMENSIONS = Object.freeze([
+  'scene_boundary',
+  'entity',
+  'relation',
+  'business_rule',
+  'decision_policy',
+  'execution_flow',
+  'failure_signal',
+  'debug_evidence_plan',
+  'verification_gate'
+]);
 
 function normalizeText(value) {
   if (typeof value !== 'string') {
@@ -79,6 +90,20 @@ mindmap
 4. Produce candidate fixes and risk tradeoffs.
 5. Define verification path and measurable acceptance.
 
+## Closed-Loop Research Coverage Matrix
+
+| Dimension | Coverage Goal | Status |
+| --- | --- | --- |
+| Scene Boundary | Entry, scope, excluded boundaries are explicit | [ ] |
+| Entity | Key entities are listed and scoped | [ ] |
+| Relation | Entity relations and direction are explicit | [ ] |
+| Business Rule | Enforceable rules are mapped | [ ] |
+| Decision Policy | Decision branches and conditions are explicit | [ ] |
+| Execution Flow | End-to-end action chain is explicit | [ ] |
+| Failure Signal | Wrong-direction signals are listed | [ ] |
+| Debug Evidence Plan | Debug-log/diagnostic evidence path is defined | [ ] |
+| Verification Gate | Acceptance and gate criteria are explicit | [ ] |
+
 ## Correction Loop
 
 - Expected Wrong-Direction Signals:
@@ -140,6 +165,12 @@ function buildSceneSpec(specId, options = {}) {
 4. Expected outputs and side effects.
 5. Failure path and rollback criteria.
 
+## Closed-Loop Research Contract
+
+- This Scene Spec is invalid if the domain mind map coverage matrix is missing.
+- Decision and execution statements must map to ontology fields in \`problem-domain-chain.json\`.
+- If two remediation rounds fail, debug evidence and diagnostic logs are mandatory before another patch round.
+
 ## Acceptance & Gate
 
 - Functional acceptance: define testable behaviors.
@@ -208,6 +239,22 @@ function buildProblemDomainChain(specId, options = {}) {
         expected_result: 'TBD: side effect and data change'
       }
     ],
+    research_coverage: {
+      mode: 'scene-closed-loop',
+      required_dimensions: [...DOMAIN_RESEARCH_DIMENSIONS],
+      checklist: {
+        scene_boundary: true,
+        entity: true,
+        relation: true,
+        business_rule: true,
+        decision_policy: true,
+        execution_flow: true,
+        failure_signal: true,
+        debug_evidence_plan: true,
+        verification_gate: true
+      },
+      status: 'draft'
+    },
     correction_loop: {
       triggers: [
         'gate failure',
@@ -236,6 +283,7 @@ function validateProblemDomainMapContent(content = '') {
     hasRootProblem: /##\s+Root Problem/i.test(content),
     hasMindMapBlock: /```mermaid[\s\S]*mindmap/i.test(content),
     hasLayeredExplorationChain: /##\s+Layered Exploration Chain/i.test(content),
+    hasCoverageMatrix: /##\s+Closed-Loop Research Coverage Matrix/i.test(content),
     hasCorrectionLoop: /##\s+Correction Loop/i.test(content)
   };
   const passed = Object.values(checks).every(Boolean);
@@ -247,6 +295,7 @@ function validateSceneSpecContent(content = '') {
     hasSceneDefinition: /##\s+Scene Definition/i.test(content),
     hasOntologyCoverage: /##\s+Ontology Coverage/i.test(content),
     hasDecisionExecutionPath: /##\s+Decision & Execution Path/i.test(content),
+    hasClosedLoopResearchContract: /##\s+Closed-Loop Research Contract/i.test(content),
     hasAcceptanceGate: /##\s+Acceptance & Gate/i.test(content)
   };
   const passed = Object.values(checks).every(Boolean);
@@ -261,7 +310,41 @@ function hasNonEmptyStringArray(value) {
   return Array.isArray(value) && value.some((item) => isNonEmptyString(item));
 }
 
+function isObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isMeaningfulText(value) {
+  if (!isNonEmptyString(value)) {
+    return false;
+  }
+  const normalized = value.trim();
+  return !/^(tbd|todo|n\/a|na|待补|待定|待完善|placeholder)\b/i.test(normalized);
+}
+
+function hasMeaningfulStringArray(value) {
+  return Array.isArray(value) && value.some((item) => isMeaningfulText(item));
+}
+
+function hasResearchCoverageChecklist(value) {
+  if (!isObject(value)) {
+    return false;
+  }
+  return DOMAIN_RESEARCH_DIMENSIONS.every((dimension) => typeof value[dimension] === 'boolean');
+}
+
+function hasResearchCoverageDimensions(value) {
+  if (!Array.isArray(value)) {
+    return false;
+  }
+  const normalized = new Set(value.map((item) => `${item || ''}`.trim()).filter(Boolean));
+  return DOMAIN_RESEARCH_DIMENSIONS.every((dimension) => normalized.has(dimension));
+}
+
 function validateProblemDomainChainPayload(payload = {}, specId = '') {
+  const researchCoverage = payload && isObject(payload.research_coverage)
+    ? payload.research_coverage
+    : null;
   const checks = {
     apiVersion: isNonEmptyString(payload.api_version),
     sceneId: isNonEmptyString(payload.scene_id),
@@ -275,6 +358,10 @@ function validateProblemDomainChainPayload(payload = {}, specId = '') {
     hasHypotheses: Array.isArray(payload.hypotheses) && payload.hypotheses.length > 0,
     hasRisks: Array.isArray(payload.risks) && payload.risks.length > 0,
     hasDecisionPath: Array.isArray(payload.decision_execution_path) && payload.decision_execution_path.length >= 3,
+    hasResearchCoverageObject: Boolean(researchCoverage),
+    hasResearchCoverageMode: isNonEmptyString(researchCoverage && researchCoverage.mode),
+    hasResearchCoverageDimensions: hasResearchCoverageDimensions(researchCoverage && researchCoverage.required_dimensions),
+    hasResearchCoverageChecklist: hasResearchCoverageChecklist(researchCoverage && researchCoverage.checklist),
     hasCorrectionTriggers: hasNonEmptyStringArray(payload?.correction_loop?.triggers),
     hasCorrectionActions: hasNonEmptyStringArray(payload?.correction_loop?.actions),
     hasVerificationGates: hasNonEmptyStringArray(payload?.verification?.gates)
@@ -285,6 +372,104 @@ function validateProblemDomainChainPayload(payload = {}, specId = '') {
   };
 }
 
+function buildDomainCoverageItems(chainPayload = {}, validation = null) {
+  const ontology = isObject(chainPayload && chainPayload.ontology) ? chainPayload.ontology : {};
+  const correctionLoop = isObject(chainPayload && chainPayload.correction_loop) ? chainPayload.correction_loop : {};
+  const verification = isObject(chainPayload && chainPayload.verification) ? chainPayload.verification : {};
+  const researchCoverage = isObject(chainPayload && chainPayload.research_coverage)
+    ? chainPayload.research_coverage
+    : {};
+
+  const structuralItems = [];
+  if (validation && isObject(validation.details)) {
+    structuralItems.push({
+      id: 'map_structure',
+      label: 'problem-domain-map structure',
+      covered: Boolean(validation.details.domain_map && validation.details.domain_map.exists && validation.details.domain_map.checks && Object.values(validation.details.domain_map.checks).every(Boolean)),
+      evidence: DOMAIN_MAP_RELATIVE_PATH
+    });
+    structuralItems.push({
+      id: 'scene_structure',
+      label: 'scene-spec structure',
+      covered: Boolean(validation.details.scene_spec && validation.details.scene_spec.exists && validation.details.scene_spec.checks && Object.values(validation.details.scene_spec.checks).every(Boolean)),
+      evidence: SCENE_SPEC_RELATIVE_PATH
+    });
+    structuralItems.push({
+      id: 'chain_structure',
+      label: 'problem-domain-chain structure',
+      covered: Boolean(validation.details.domain_chain && validation.details.domain_chain.exists && validation.details.domain_chain.checks && Object.values(validation.details.domain_chain.checks).every(Boolean)),
+      evidence: DOMAIN_CHAIN_RELATIVE_PATH
+    });
+  }
+
+  const domainItems = [
+    {
+      id: 'scene_boundary',
+      label: 'Scene boundary',
+      covered: isMeaningfulText(chainPayload?.problem?.statement) && isMeaningfulText(chainPayload?.problem?.scope),
+      evidence: 'problem.statement + problem.scope'
+    },
+    {
+      id: 'entity',
+      label: 'Ontology entity coverage',
+      covered: hasMeaningfulStringArray(ontology.entity),
+      evidence: 'ontology.entity[]'
+    },
+    {
+      id: 'relation',
+      label: 'Ontology relation coverage',
+      covered: hasMeaningfulStringArray(ontology.relation),
+      evidence: 'ontology.relation[]'
+    },
+    {
+      id: 'business_rule',
+      label: 'Business rule coverage',
+      covered: hasMeaningfulStringArray(ontology.business_rule),
+      evidence: 'ontology.business_rule[]'
+    },
+    {
+      id: 'decision_policy',
+      label: 'Decision policy coverage',
+      covered: hasMeaningfulStringArray(ontology.decision_policy),
+      evidence: 'ontology.decision_policy[]'
+    },
+    {
+      id: 'execution_flow',
+      label: 'Execution flow coverage',
+      covered: hasMeaningfulStringArray(ontology.execution_flow),
+      evidence: 'ontology.execution_flow[]'
+    },
+    {
+      id: 'failure_signal',
+      label: 'Failure-signal coverage',
+      covered: hasMeaningfulStringArray(correctionLoop.triggers),
+      evidence: 'correction_loop.triggers[]'
+    },
+    {
+      id: 'debug_evidence_plan',
+      label: 'Debug evidence plan',
+      covered: Array.isArray(correctionLoop.actions)
+        && correctionLoop.actions.some((item) => /debug|diagnostic|日志|evidence/i.test(`${item || ''}`)),
+      evidence: 'correction_loop.actions[]'
+    },
+    {
+      id: 'verification_gate',
+      label: 'Verification gate coverage',
+      covered: hasMeaningfulStringArray(verification.gates),
+      evidence: 'verification.gates[]'
+    },
+    {
+      id: 'research_contract',
+      label: 'Research contract checklist',
+      covered: hasResearchCoverageChecklist(researchCoverage.checklist)
+        && hasResearchCoverageDimensions(researchCoverage.required_dimensions),
+      evidence: 'research_coverage.required_dimensions + checklist'
+    }
+  ];
+
+  return [...structuralItems, ...domainItems];
+}
+
 async function ensureSpecDomainArtifacts(projectPath, specId, options = {}) {
   const fileSystem = options.fileSystem || fs;
   const dryRun = options.dryRun === true;
@@ -426,14 +611,45 @@ async function validateSpecDomainArtifacts(projectPath, specId, fileSystem = fs)
   };
 }
 
+async function analyzeSpecDomainCoverage(projectPath, specId, fileSystem = fs) {
+  const validation = await validateSpecDomainArtifacts(projectPath, specId, fileSystem);
+  const paths = resolveSpecPaths(projectPath, specId);
+  let chainPayload = null;
+
+  if (await fileSystem.pathExists(paths.domainChainPath)) {
+    try {
+      chainPayload = await fileSystem.readJson(paths.domainChainPath);
+    } catch (_error) {
+      chainPayload = null;
+    }
+  }
+
+  const items = buildDomainCoverageItems(chainPayload || {}, validation);
+  const coveredCount = items.filter((item) => item.covered).length;
+  const totalCount = items.length;
+  const uncovered = items.filter((item) => !item.covered).map((item) => item.id);
+
+  return {
+    passed: uncovered.length === 0,
+    coverage_ratio: totalCount > 0 ? coveredCount / totalCount : 0,
+    covered_count: coveredCount,
+    total_count: totalCount,
+    uncovered,
+    items,
+    validation
+  };
+}
+
 module.exports = {
   DOMAIN_MAP_RELATIVE_PATH,
   SCENE_SPEC_RELATIVE_PATH,
   DOMAIN_CHAIN_RELATIVE_PATH,
   DOMAIN_CHAIN_API_VERSION,
+  DOMAIN_RESEARCH_DIMENSIONS,
   buildProblemDomainMindMap,
   buildSceneSpec,
   buildProblemDomainChain,
   ensureSpecDomainArtifacts,
-  validateSpecDomainArtifacts
+  validateSpecDomainArtifacts,
+  analyzeSpecDomainCoverage
 };