scene-capability-engine 3.3.26 → 3.4.6

package/lib/spec/domain-modeling.js

@@ -4,7 +4,19 @@ const path = require('path');
 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 PROBLEM_CONTRACT_RELATIVE_PATH = path.join('custom', 'problem-contract.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') {
@@ -19,7 +31,30 @@ function resolveSpecPaths(projectPath, specId) {
     specPath,
     domainMapPath: path.join(specPath, DOMAIN_MAP_RELATIVE_PATH),
     sceneSpecPath: path.join(specPath, SCENE_SPEC_RELATIVE_PATH),
-    domainChainPath: path.join(specPath, DOMAIN_CHAIN_RELATIVE_PATH)
+    domainChainPath: path.join(specPath, DOMAIN_CHAIN_RELATIVE_PATH),
+    problemContractPath: path.join(specPath, PROBLEM_CONTRACT_RELATIVE_PATH)
+  };
+}
+
+function buildProblemContract(specId, options = {}) {
+  const sceneId = normalizeText(options.sceneId) || `scene.${specId.replace(/[^a-zA-Z0-9]+/g, '-').toLowerCase()}`;
+  const problemStatement = normalizeText(options.problemStatement) || 'TBD: describe the primary business problem';
+  const verificationPlan = normalizeText(options.verificationPlan) || 'TBD: define validation and rollback criteria';
+  return {
+    schema_version: '1.0',
+    spec_id: specId,
+    scene_id: sceneId,
+    issue_statement: problemStatement,
+    expected_outcome: verificationPlan,
+    reproduction_steps: [
+      'Reproduce the issue along the failing scene path.',
+      'Capture gate/test/runtime evidence for failed behavior.'
+    ],
+    impact_scope: `scene=${sceneId}`,
+    forbidden_workarounds: [
+      'Do not bypass mandatory gates or tests.',
+      'Do not silence runtime errors without root-cause remediation.'
+    ]
   };
 }
 
@@ -79,6 +114,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 +189,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 +263,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',
@@ -227,6 +298,14 @@ function buildProblemDomainChain(specId, options = {}) {
         'tests',
         'release preflight'
       ]
+    },
+    problem_contract: buildProblemContract(specId, options),
+    ontology_evidence: {
+      entity: ['Entity mapping evidence: model/schema reference'],
+      relation: ['Relation mapping evidence: join/foreign-key or service linkage'],
+      business_rule: ['Rule evidence: validation/policy check reference'],
+      decision_policy: ['Decision evidence: branch condition and policy source'],
+      execution_flow: ['Execution evidence: service/screen/runtime trace path']
     }
   };
 }
@@ -236,6 +315,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 +327,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 +342,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 +390,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 +404,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;
@@ -294,11 +511,13 @@ async function ensureSpecDomainArtifacts(projectPath, specId, options = {}) {
   const domainMapContent = buildProblemDomainMindMap(specId, options);
   const sceneSpecContent = buildSceneSpec(specId, options);
   const domainChainPayload = buildProblemDomainChain(specId, options);
+  const problemContractPayload = buildProblemContract(specId, options);
 
   const created = {
     domain_map: false,
     scene_spec: false,
-    domain_chain: false
+    domain_chain: false,
+    problem_contract: false
   };
 
   if (!dryRun) {
@@ -321,23 +540,32 @@ async function ensureSpecDomainArtifacts(projectPath, specId, options = {}) {
       await fileSystem.writeJson(paths.domainChainPath, domainChainPayload, { spaces: 2 });
       created.domain_chain = true;
     }
+
+    const hasProblemContract = await fileSystem.pathExists(paths.problemContractPath);
+    if (force || !hasProblemContract) {
+      await fileSystem.writeJson(paths.problemContractPath, problemContractPayload, { spaces: 2 });
+      created.problem_contract = true;
+    }
   } else {
     created.domain_map = true;
     created.scene_spec = true;
     created.domain_chain = true;
+    created.problem_contract = true;
   }
 
   return {
     paths: {
       domain_map: paths.domainMapPath,
       scene_spec: paths.sceneSpecPath,
-      domain_chain: paths.domainChainPath
+      domain_chain: paths.domainChainPath,
+      problem_contract: paths.problemContractPath
     },
     created,
     preview: {
       domain_map: domainMapContent,
       scene_spec: sceneSpecContent,
-      domain_chain: domainChainPayload
+      domain_chain: domainChainPayload,
+      problem_contract: problemContractPayload
     }
   };
 }
@@ -426,14 +654,47 @@ 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,
+  PROBLEM_CONTRACT_RELATIVE_PATH,
   DOMAIN_CHAIN_API_VERSION,
+  DOMAIN_RESEARCH_DIMENSIONS,
   buildProblemDomainMindMap,
   buildSceneSpec,
   buildProblemDomainChain,
+  buildProblemContract,
   ensureSpecDomainArtifacts,
-  validateSpecDomainArtifacts
+  validateSpecDomainArtifacts,
+  analyzeSpecDomainCoverage
 };