scene-capability-engine 3.4.5 → 3.5.0

package/lib/problem/problem-evaluator.js

@@ -6,6 +6,7 @@ const DEFAULT_POLICY_PATH = '.sce/config/problem-eval-policy.json';
 const DEFAULT_REPORT_DIR = '.sce/reports/problem-eval';
 const STUDIO_STAGES = Object.freeze(['plan', 'generate', 'apply', 'verify', 'release']);
 const DEBUG_EVIDENCE_TAGS = Object.freeze(['debug-evidence', 'diagnostic-evidence', 'debug-log']);
+const ONTOLOGY_AXES = Object.freeze(['entity', 'relation', 'business_rule', 'decision_policy', 'execution_flow']);
 
 const DEFAULT_PROBLEM_EVAL_POLICY = Object.freeze({
   schema_version: '1.0',
@@ -32,7 +33,19 @@ const DEFAULT_PROBLEM_EVAL_POLICY = Object.freeze({
     'compliance',
     'data-loss'
   ],
-  recommendation_limit: 6
+  recommendation_limit: 6,
+  max_failed_rounds_before_debug: 2,
+  problem_contract_required_stages: [...STUDIO_STAGES],
+  problem_contract_block_stages: ['plan', 'apply', 'release'],
+  ontology_alignment_required_stages: [...STUDIO_STAGES],
+  ontology_alignment_block_stages: ['apply', 'release'],
+  ontology_required_axes: [...ONTOLOGY_AXES],
+  require_ontology_evidence_binding: true,
+  ontology_evidence_min_bindings: 1,
+  convergence_required_stages: ['verify', 'release'],
+  convergence_block_stages: ['release'],
+  release_block_on_high_alerts: true,
+  release_require_governance_report: false
 });
 
 function normalizeText(value) {
@@ -84,6 +97,36 @@ function normalizeArray(value = []) {
   return value.map((item) => normalizeText(item)).filter(Boolean);
 }
 
+function normalizeTextList(value = [], limit = 20) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => {
+      if (typeof item === 'string') {
+        return normalizeText(item);
+      }
+      if (item && typeof item === 'object') {
+        return normalizeText(item.step || item.description || item.id || item.name || '');
+      }
+      return '';
+    })
+    .filter(Boolean)
+    .slice(0, limit);
+}
+
+function normalizeStageArray(value, fallback = []) {
+  const candidates = normalizeArray(value).map((item) => item.toLowerCase());
+  const filtered = candidates.filter((item, index) => STUDIO_STAGES.includes(item) && candidates.indexOf(item) === index);
+  return filtered.length > 0 ? filtered : [...fallback];
+}
+
+function normalizeOntologyAxisArray(value, fallback = []) {
+  const candidates = normalizeArray(value).map((item) => item.toLowerCase());
+  const filtered = candidates.filter((item, index) => ONTOLOGY_AXES.includes(item) && candidates.indexOf(item) === index);
+  return filtered.length > 0 ? filtered : [...fallback];
+}
+
 function normalizeIncidentState(value, fallback = 'open') {
   const normalized = normalizeLowerText(value);
   if (!normalized) {
@@ -133,12 +176,14 @@ function normalizePolicy(policy = {}, env = process.env) {
     schema_version: normalizeText(policy.schema_version) || DEFAULT_PROBLEM_EVAL_POLICY.schema_version,
     enabled,
     mode: mode || DEFAULT_PROBLEM_EVAL_POLICY.mode,
-    enforce_on_stages: normalizeArray(policy.enforce_on_stages).length > 0
-      ? normalizeArray(policy.enforce_on_stages).map((item) => item.toLowerCase())
-      : [...DEFAULT_PROBLEM_EVAL_POLICY.enforce_on_stages],
-    block_on_stages: normalizeArray(policy.block_on_stages).length > 0
-      ? normalizeArray(policy.block_on_stages).map((item) => item.toLowerCase())
-      : [...DEFAULT_PROBLEM_EVAL_POLICY.block_on_stages],
+    enforce_on_stages: normalizeStageArray(
+      policy.enforce_on_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.enforce_on_stages
+    ),
+    block_on_stages: normalizeStageArray(
+      policy.block_on_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.block_on_stages
+    ),
     min_confidence_by_stage: {
       plan: normalizeInteger(minByStage.plan, DEFAULT_PROBLEM_EVAL_POLICY.min_confidence_by_stage.plan, 0, 100),
       generate: normalizeInteger(minByStage.generate, DEFAULT_PROBLEM_EVAL_POLICY.min_confidence_by_stage.generate, 0, 100),
@@ -158,6 +203,58 @@ function normalizePolicy(policy = {}, env = process.env) {
       DEFAULT_PROBLEM_EVAL_POLICY.recommendation_limit,
       1,
       20
+    ),
+    max_failed_rounds_before_debug: normalizeInteger(
+      policy.max_failed_rounds_before_debug,
+      DEFAULT_PROBLEM_EVAL_POLICY.max_failed_rounds_before_debug,
+      1,
+      10
+    ),
+    problem_contract_required_stages: normalizeStageArray(
+      policy.problem_contract_required_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.problem_contract_required_stages
+    ),
+    problem_contract_block_stages: normalizeStageArray(
+      policy.problem_contract_block_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.problem_contract_block_stages
+    ),
+    ontology_alignment_required_stages: normalizeStageArray(
+      policy.ontology_alignment_required_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.ontology_alignment_required_stages
+    ),
+    ontology_alignment_block_stages: normalizeStageArray(
+      policy.ontology_alignment_block_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.ontology_alignment_block_stages
+    ),
+    ontology_required_axes: normalizeOntologyAxisArray(
+      policy.ontology_required_axes,
+      DEFAULT_PROBLEM_EVAL_POLICY.ontology_required_axes
+    ),
+    require_ontology_evidence_binding: normalizeBoolean(
+      policy.require_ontology_evidence_binding,
+      DEFAULT_PROBLEM_EVAL_POLICY.require_ontology_evidence_binding
+    ),
+    ontology_evidence_min_bindings: normalizeInteger(
+      policy.ontology_evidence_min_bindings,
+      DEFAULT_PROBLEM_EVAL_POLICY.ontology_evidence_min_bindings,
+      0,
+      20
+    ),
+    convergence_required_stages: normalizeStageArray(
+      policy.convergence_required_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.convergence_required_stages
+    ),
+    convergence_block_stages: normalizeStageArray(
+      policy.convergence_block_stages,
+      DEFAULT_PROBLEM_EVAL_POLICY.convergence_block_stages
+    ),
+    release_block_on_high_alerts: normalizeBoolean(
+      policy.release_block_on_high_alerts,
+      DEFAULT_PROBLEM_EVAL_POLICY.release_block_on_high_alerts
+    ),
+    release_require_governance_report: normalizeBoolean(
+      policy.release_require_governance_report,
+      DEFAULT_PROBLEM_EVAL_POLICY.release_require_governance_report
     )
   };
 
@@ -226,7 +323,8 @@ function scoreRisk(stage, text, policy, incidentSignals = {}, releaseChannel = '
     score += Math.min(20, openIncidents * 3);
     signals.push(`open-incidents:${openIncidents}`);
   }
-  if (maxAttempts >= 3) {
+  const debugRoundThreshold = Number(policy.max_failed_rounds_before_debug || 2) + 1;
+  if (maxAttempts >= debugRoundThreshold) {
     score += 16;
     signals.push(`repeat-attempts:${maxAttempts}`);
   }
@@ -242,15 +340,262 @@ function scoreRisk(stage, text, policy, incidentSignals = {}, releaseChannel = '
   return { score, level, signals };
 }
 
+function stageInPolicy(stage, list = []) {
+  return Array.isArray(list) && list.includes(stage);
+}
+
+function countOntologyEvidenceBindings(domainChain = {}, summary = {}) {
+  const summaryCount = Number(summary.evidence_binding_count || 0);
+  if (Number.isFinite(summaryCount) && summaryCount > 0) {
+    return summaryCount;
+  }
+
+  let total = 0;
+  const explicitBindings = Array.isArray(domainChain.evidence_bindings)
+    ? domainChain.evidence_bindings.length
+    : 0;
+  total += explicitBindings;
+
+  const ontologyEvidence = domainChain.ontology_evidence && typeof domainChain.ontology_evidence === 'object'
+    ? domainChain.ontology_evidence
+    : {};
+  for (const axis of ONTOLOGY_AXES) {
+    total += normalizeTextList(ontologyEvidence[axis], 50).length;
+  }
+
+  const hypotheses = Array.isArray(domainChain.hypotheses) ? domainChain.hypotheses : [];
+  for (const hypothesis of hypotheses.slice(0, 30)) {
+    total += normalizeTextList(hypothesis && hypothesis.evidence, 20).length;
+  }
+
+  return total;
+}
+
+function extractDomainChainSummary(domainChain = {}) {
+  const summary = domainChain.summary && typeof domainChain.summary === 'object'
+    ? domainChain.summary
+    : {};
+  const payloadOntology = domainChain.ontology && typeof domainChain.ontology === 'object'
+    ? domainChain.ontology
+    : {};
+
+  const fallbackCounts = {
+    entity: normalizeTextList(payloadOntology.entity, 50).length,
+    relation: normalizeTextList(payloadOntology.relation, 50).length,
+    business_rule: normalizeTextList(payloadOntology.business_rule, 50).length,
+    decision_policy: normalizeTextList(payloadOntology.decision_policy, 50).length,
+    execution_flow: normalizeTextList(payloadOntology.execution_flow, 50).length
+  };
+
+  const summaryCounts = summary.ontology_counts && typeof summary.ontology_counts === 'object'
+    ? summary.ontology_counts
+    : {};
+  const ontologyCounts = {
+    entity: Number(summaryCounts.entity || fallbackCounts.entity || 0),
+    relation: Number(summaryCounts.relation || fallbackCounts.relation || 0),
+    business_rule: Number(summaryCounts.business_rule || fallbackCounts.business_rule || 0),
+    decision_policy: Number(summaryCounts.decision_policy || fallbackCounts.decision_policy || 0),
+    execution_flow: Number(summaryCounts.execution_flow || fallbackCounts.execution_flow || 0)
+  };
+
+  return {
+    ontology_counts: ontologyCounts,
+    decision_path_steps: Number(
+      summary.decision_path_steps
+      || (Array.isArray(domainChain.decision_execution_path) ? domainChain.decision_execution_path.length : 0)
+      || 0
+    ),
+    verification_gates: Array.isArray(summary.verification_gates)
+      ? summary.verification_gates
+      : (domainChain?.verification?.gates && Array.isArray(domainChain.verification.gates) ? domainChain.verification.gates : []),
+    hypothesis_count: Number(summary.hypothesis_count || (Array.isArray(domainChain.hypotheses) ? domainChain.hypotheses.length : 0) || 0),
+    risk_count: Number(summary.risk_count || (Array.isArray(domainChain.risks) ? domainChain.risks.length : 0) || 0),
+    evidence_binding_count: countOntologyEvidenceBindings(domainChain, summary)
+  };
+}
+
+function deriveProblemContract(context = {}) {
+  const domainChain = context.domain_chain && typeof context.domain_chain === 'object'
+    ? context.domain_chain
+    : {};
+  const chainContext = domainChain.context && typeof domainChain.context === 'object'
+    ? domainChain.context
+    : {};
+  const contractRaw = context.problem_contract && typeof context.problem_contract === 'object'
+    ? context.problem_contract
+    : {};
+
+  const issueStatement = normalizeText(
+    contractRaw.issue_statement
+    || contractRaw.issue
+    || contractRaw.problem_statement
+    || chainContext?.problem?.statement
+    || domainChain?.problem?.statement
+    || context.goal
+    || (context.scene_id ? `Stabilize scene ${normalizeText(context.scene_id)} execution.` : '')
+  );
+  const expectedOutcome = normalizeText(
+    contractRaw.expected_outcome
+    || contractRaw.expected
+    || contractRaw.success_criteria
+    || chainContext?.verification?.plan
+    || domainChain?.verification?.plan
+    || (context.scene_id ? `Scene ${normalizeText(context.scene_id)} reaches deterministic verification gates.` : '')
+  );
+  const reproductionStepsRaw = normalizeTextList(
+    contractRaw.reproduction_steps
+    || contractRaw.repro_steps
+    || contractRaw.steps,
+    20
+  );
+  const reproductionSteps = reproductionStepsRaw.length > 0
+    ? reproductionStepsRaw
+    : [
+      normalizeText(context.goal) || 'Reproduce the reported failure path in the target scene.',
+      'Capture execution trace and gate evidence for the failing path.'
+    ].filter(Boolean);
+  const impactScope = normalizeText(
+    contractRaw.impact_scope
+    || contractRaw.scope
+    || chainContext?.problem?.scope
+    || domainChain?.problem?.scope
+    || context.scene_id
+  );
+  const forbiddenWorkaroundsRaw = normalizeTextList(
+    contractRaw.forbidden_workarounds
+    || contractRaw.prohibited_workarounds
+    || contractRaw.disallowed_workarounds,
+    20
+  );
+  const forbiddenWorkarounds = forbiddenWorkaroundsRaw.length > 0
+    ? forbiddenWorkaroundsRaw
+    : [
+      'Do not bypass mandatory gates or tests.',
+      'Do not silence errors without root-cause remediation.'
+    ];
+  return {
+    issue_statement: issueStatement,
+    expected_outcome: expectedOutcome,
+    reproduction_steps: reproductionSteps,
+    impact_scope: impactScope,
+    forbidden_workarounds: forbiddenWorkarounds
+  };
+}
+
+function evaluateProblemContract(context = {}) {
+  const contract = deriveProblemContract(context);
+  const checks = {
+    issue_statement: normalizeText(contract.issue_statement).length > 0,
+    expected_outcome: normalizeText(contract.expected_outcome).length > 0,
+    reproduction_steps: Array.isArray(contract.reproduction_steps) && contract.reproduction_steps.length > 0,
+    impact_scope: normalizeText(contract.impact_scope).length > 0,
+    forbidden_workarounds: Array.isArray(contract.forbidden_workarounds) && contract.forbidden_workarounds.length > 0
+  };
+  const total = Object.keys(checks).length;
+  const covered = Object.values(checks).filter(Boolean).length;
+  return {
+    contract,
+    checks,
+    total,
+    covered,
+    missing: Object.keys(checks).filter((key) => !checks[key]),
+    score: Math.round((covered / total) * 100),
+    passed: covered === total
+  };
+}
+
+function evaluateOntologyAlignment(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLICY) {
+  const domainChain = context.domain_chain && typeof context.domain_chain === 'object'
+    ? context.domain_chain
+    : {};
+  const summary = extractDomainChainSummary(domainChain);
+  const requiredAxes = Array.isArray(policy.ontology_required_axes) && policy.ontology_required_axes.length > 0
+    ? policy.ontology_required_axes
+    : [...ONTOLOGY_AXES];
+  const missingAxes = requiredAxes.filter((axis) => Number(summary?.ontology_counts?.[axis] || 0) <= 0);
+  const evidenceBindingCount = Number(summary.evidence_binding_count || 0);
+  const minBindings = Number(policy.ontology_evidence_min_bindings || 0);
+  const hasDomainMaterial = domainChain.resolved === true
+    || ONTOLOGY_AXES.some((axis) => Number(summary?.ontology_counts?.[axis] || 0) > 0)
+    || normalizeText(context.spec_id).length > 0;
+  if (!hasDomainMaterial) {
+    return {
+      required_axes: requiredAxes,
+      missing_axes: [],
+      ontology_counts: summary.ontology_counts,
+      evidence_binding_count: evidenceBindingCount,
+      required_evidence_bindings: minBindings,
+      evidence_satisfied: true,
+      score: 100,
+      passed: true,
+      skipped: true
+    };
+  }
+  const evidenceSatisfied = policy.require_ontology_evidence_binding !== true
+    ? true
+    : evidenceBindingCount >= minBindings;
+
+  let score = 0;
+  if (requiredAxes.length > 0) {
+    score += Math.round(((requiredAxes.length - missingAxes.length) / requiredAxes.length) * 80);
+  }
+  if (evidenceSatisfied) {
+    score += 20;
+  }
+  score = Math.max(0, Math.min(100, score));
+
+  return {
+    required_axes: requiredAxes,
+    missing_axes: missingAxes,
+    ontology_counts: summary.ontology_counts,
+    evidence_binding_count: evidenceBindingCount,
+    required_evidence_bindings: minBindings,
+    evidence_satisfied: evidenceSatisfied,
+    score,
+    passed: missingAxes.length === 0 && evidenceSatisfied
+  };
+}
+
+function evaluateConvergence(context = {}, stage = '', policy = DEFAULT_PROBLEM_EVAL_POLICY) {
+  const readiness = context.stage_readiness && typeof context.stage_readiness === 'object'
+    ? context.stage_readiness
+    : {};
+  const checks = {
+    prerequisites_ready: readiness.prerequisites_ready === true
+  };
+  if (stage === 'release') {
+    checks.verify_report_ready = readiness.verify_report_ready === true;
+    checks.verify_stage_passed = readiness.verify_stage_passed !== false;
+    checks.regression_passed = readiness.regression_passed !== false;
+    const highAlertCount = Number(readiness.high_alert_count || 0);
+    checks.high_alerts_clear = policy.release_block_on_high_alerts === true
+      ? highAlertCount <= 0
+      : true;
+    if (policy.release_require_governance_report === true) {
+      checks.governance_report_ready = readiness.governance_report_ready === true;
+    }
+  }
+
+  const total = Object.keys(checks).length;
+  const covered = Object.values(checks).filter(Boolean).length;
+  const missing = Object.keys(checks).filter((key) => !checks[key]);
+  const score = total > 0 ? Math.round((covered / total) * 100) : 100;
+
+  return {
+    checks,
+    missing,
+    score,
+    passed: missing.length === 0
+  };
+}
+
 function scoreEvidence(context = {}, incidentSignals = {}) {
   const signals = [];
   let score = 0;
   const domainChain = context.domain_chain && typeof context.domain_chain === 'object'
     ? context.domain_chain
     : {};
-  const summary = domainChain.summary && typeof domainChain.summary === 'object'
-    ? domainChain.summary
-    : {};
+  const summary = extractDomainChainSummary(domainChain);
 
   if (domainChain.resolved === true) {
     score += 20;
@@ -293,6 +638,11 @@ function scoreEvidence(context = {}, incidentSignals = {}) {
     score += 6;
     signals.push('required-gates-available');
   }
+  const evidenceBindingCount = Number(summary.evidence_binding_count || 0);
+  if (evidenceBindingCount > 0) {
+    score += Math.min(10, evidenceBindingCount);
+    signals.push(`ontology-evidence-bindings:${evidenceBindingCount}`);
+  }
 
   score = Math.max(0, Math.min(100, Math.round(score)));
   return { score, signals };
@@ -347,7 +697,8 @@ function scoreReadiness(context = {}) {
 function deriveStrategy(stage, risk, evidence, confidence, incidentSignals = {}, policy = DEFAULT_PROBLEM_EVAL_POLICY) {
   const reasons = [];
   let strategy = 'direct-execution';
-  if (Number(incidentSignals.max_attempt_count || 0) >= 3
+  const debugAttemptThreshold = Number(policy.max_failed_rounds_before_debug || 2) + 1;
+  if (Number(incidentSignals.max_attempt_count || 0) >= debugAttemptThreshold
     && policy.high_risk_requires_debug_evidence
     && incidentSignals.has_debug_evidence !== true) {
     strategy = 'debug-first';
@@ -393,8 +744,16 @@ function evaluateProblemContext(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLI
   const risk = scoreRisk(stage, textForRisk, policy, incidentSignals, context.release_channel);
   const evidence = scoreEvidence(context, incidentSignals);
   const readiness = scoreReadiness(context);
+  const problemContract = evaluateProblemContract(context);
+  const ontologyAlignment = evaluateOntologyAlignment(context, policy);
+  const convergence = evaluateConvergence(context, stage, policy);
   const confidenceScore = Math.max(0, Math.min(100, Math.round(
-    evidence.score * 0.45 + readiness.score * 0.35 + (100 - risk.score) * 0.20
+    evidence.score * 0.32
+    + readiness.score * 0.24
+    + (100 - risk.score) * 0.14
+    + problemContract.score * 0.15
+    + ontologyAlignment.score * 0.10
+    + convergence.score * 0.05
   )));
 
   const minConfidence = Number(policy?.min_confidence_by_stage?.[stage] || 0);
@@ -413,9 +772,10 @@ function evaluateProblemContext(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLI
     }
   }
 
+  const debugAttemptThreshold = Number(policy.max_failed_rounds_before_debug || 2) + 1;
   if (policy.high_risk_requires_debug_evidence
     && risk.level === 'high'
-    && Number(incidentSignals.max_attempt_count || 0) >= 3
+    && Number(incidentSignals.max_attempt_count || 0) >= debugAttemptThreshold
     && incidentSignals.has_debug_evidence !== true) {
     warnings.push('high risk with repeated failed attempts and no debug evidence');
     if (blockStage) {
@@ -430,6 +790,47 @@ function evaluateProblemContext(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLI
     }
   }
 
+  const problemContractRequired = stageInPolicy(stage, policy.problem_contract_required_stages);
+  const problemContractBlockedStage = stageInPolicy(stage, policy.problem_contract_block_stages);
+  if (problemContractRequired && !problemContract.passed) {
+    warnings.push(`problem contract incomplete: ${problemContract.missing.join(', ')}`);
+    if (problemContractBlockedStage) {
+      blockers.push(`problem-contract-incomplete:${problemContract.missing.join('|')}`);
+    }
+  }
+
+  const ontologyRequired = stageInPolicy(stage, policy.ontology_alignment_required_stages);
+  const ontologyBlockedStage = stageInPolicy(stage, policy.ontology_alignment_block_stages);
+  if (ontologyRequired && !ontologyAlignment.passed) {
+    if (ontologyAlignment.missing_axes.length > 0) {
+      warnings.push(`ontology alignment missing axes: ${ontologyAlignment.missing_axes.join(', ')}`);
+    }
+    if (!ontologyAlignment.evidence_satisfied) {
+      warnings.push(
+        `ontology evidence binding below threshold: ${ontologyAlignment.evidence_binding_count}<${ontologyAlignment.required_evidence_bindings}`
+      );
+    }
+    if (ontologyBlockedStage) {
+      if (ontologyAlignment.missing_axes.length > 0) {
+        blockers.push(`ontology-alignment-missing:${ontologyAlignment.missing_axes.join('|')}`);
+      }
+      if (!ontologyAlignment.evidence_satisfied) {
+        blockers.push(
+          `ontology-evidence-binding-low:${ontologyAlignment.evidence_binding_count}<${ontologyAlignment.required_evidence_bindings}`
+        );
+      }
+    }
+  }
+
+  const convergenceRequired = stageInPolicy(stage, policy.convergence_required_stages);
+  const convergenceBlockedStage = stageInPolicy(stage, policy.convergence_block_stages);
+  if (convergenceRequired && !convergence.passed) {
+    warnings.push(`convergence checks pending: ${convergence.missing.join(', ')}`);
+    if (convergenceBlockedStage) {
+      blockers.push(`convergence-gate-missing:${convergence.missing.join('|')}`);
+    }
+  }
+
   const recommendations = [];
   if (strategy.strategy === 'debug-first') {
     recommendations.push('Capture debug trace/log evidence before the next patch attempt.');
@@ -444,12 +845,22 @@ function evaluateProblemContext(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLI
   if (Number(incidentSignals.open_incident_count || 0) > 0) {
     recommendations.push('Review staging incident attempts to avoid repeating failed actions.');
   }
+  if (!problemContract.passed) {
+    recommendations.push('Complete the problem contract: issue, expected outcome, reproduction steps, impact scope, and forbidden workarounds.');
+  }
+  if (!ontologyAlignment.passed) {
+    recommendations.push('Fill missing ontology axes and bind evidence references before further remediation.');
+  }
+  if (!convergence.passed) {
+    recommendations.push('Close convergence checks (verify pass, regression pass, high-alert clear) before release.');
+  }
   if (recommendations.length === 0) {
     recommendations.push('Proceed with direct execution and keep gate verification enabled.');
   }
 
   const cappedRecommendations = recommendations.slice(0, policy.recommendation_limit || 6);
-  const blocked = enforced && blockStage && !advisoryMode && blockers.length > 0;
+  const hardBlockStage = blockStage || problemContractBlockedStage || ontologyBlockedStage || convergenceBlockedStage;
+  const blocked = enforced && hardBlockStage && !advisoryMode && blockers.length > 0;
 
   return {
     mode: 'problem-eval',
@@ -464,13 +875,17 @@ function evaluateProblemContext(context = {}, policy = DEFAULT_PROBLEM_EVAL_POLI
       mode: policy.mode,
       enforced,
       block_stage: blockStage,
+      hard_block_stage: hardBlockStage,
       min_confidence: minConfidence
     },
     dimensions: {
       risk,
       evidence,
       readiness,
-      strategy
+      strategy,
+      problem_contract: problemContract,
+      ontology_alignment: ontologyAlignment,
+      convergence
     },
     incident_signals: {
       ...incidentSignals

package/lib/spec/domain-modeling.js

@@ -4,6 +4,7 @@ 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',
@@ -30,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.'
+    ]
   };
 }
 
@@ -274,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']
     }
   };
 }
@@ -479,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) {
@@ -506,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
     }
   };
 }
@@ -644,11 +687,13 @@ 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,
   analyzeSpecDomainCoverage