scene-capability-engine 3.6.32 → 3.6.36

package/lib/auto/handoff-capability-matrix-service.js

@@ -0,0 +1,281 @@
+function buildAutoHandoffCapabilityMatrixPolicy(options = {}, dependencies = {}) {
+  const {
+    resolveAutoHandoffPolicyPreset,
+    normalizeHandoffMinCapabilityCoverage,
+    resolveAutoHandoffPolicyOptionNumber,
+    normalizeHandoffMinCapabilitySemantic,
+    resolveAutoHandoffPolicyOptionBoolean
+  } = dependencies;
+  const { profile, preset } = resolveAutoHandoffPolicyPreset(options.profile, '--profile');
+  return {
+    profile,
+    min_capability_coverage_percent: normalizeHandoffMinCapabilityCoverage(
+      resolveAutoHandoffPolicyOptionNumber(
+        options.minCapabilityCoverage,
+        preset.min_capability_coverage_percent
+      )
+    ),
+    min_capability_semantic_percent: normalizeHandoffMinCapabilitySemantic(
+      resolveAutoHandoffPolicyOptionNumber(
+        options.minCapabilitySemantic,
+        preset.min_capability_semantic_percent
+      )
+    ),
+    require_capability_coverage: resolveAutoHandoffPolicyOptionBoolean(
+      options.requireCapabilityCoverage,
+      preset.require_capability_coverage
+    ),
+    require_capability_semantic: resolveAutoHandoffPolicyOptionBoolean(
+      options.requireCapabilitySemantic,
+      preset.require_capability_semantic
+    ),
+    require_capability_lexicon: resolveAutoHandoffPolicyOptionBoolean(
+      options.requireCapabilityLexicon,
+      preset.require_capability_lexicon
+    ),
+    require_moqui_baseline: resolveAutoHandoffPolicyOptionBoolean(
+      options.requireMoquiBaseline,
+      preset.require_moqui_baseline
+    )
+  };
+}
+
+function buildAutoHandoffCapabilityMatrixRecommendations(result = {}, dependencies = {}) {
+  const {
+    normalizeHandoffText,
+    quoteCliArg,
+    buildAutoHandoffMoquiCoverageRegressions,
+    buildMoquiRegressionRecoverySequenceLines,
+    clusterRemediationFile,
+    baselineJsonFile
+  } = dependencies;
+
+  const recommendations = [];
+  const push = value => {
+    const text = `${value || ''}`.trim();
+    if (!text || recommendations.includes(text)) {
+      return;
+    }
+    recommendations.push(text);
+  };
+
+  const manifestPath = normalizeHandoffText(result && result.manifest_path);
+  const manifestCli = manifestPath ? quoteCliArg(manifestPath) : '<path>';
+  const templateDiff = result && result.template_diff && typeof result.template_diff === 'object'
+    ? result.template_diff
+    : {};
+  const capabilityCoverage = result && result.capability_coverage && typeof result.capability_coverage === 'object'
+    ? result.capability_coverage
+    : {};
+  const coverageSummary = capabilityCoverage && capabilityCoverage.summary && typeof capabilityCoverage.summary === 'object'
+    ? capabilityCoverage.summary
+    : {};
+  const coverageNormalization = capabilityCoverage && capabilityCoverage.normalization &&
+    typeof capabilityCoverage.normalization === 'object'
+    ? capabilityCoverage.normalization
+    : {};
+  const expectedUnknownCount = Array.isArray(coverageNormalization.expected_unknown)
+    ? coverageNormalization.expected_unknown.length
+    : 0;
+  const providedUnknownCount = Array.isArray(coverageNormalization.provided_unknown)
+    ? coverageNormalization.provided_unknown.length
+    : 0;
+  const baseline = result && result.moqui_baseline && typeof result.moqui_baseline === 'object'
+    ? result.moqui_baseline
+    : {};
+  const baselineCompare = baseline && baseline.compare && typeof baseline.compare === 'object'
+    ? baseline.compare
+    : {};
+  const baselineRegressions = buildAutoHandoffMoquiCoverageRegressions(baselineCompare);
+
+  if (templateDiff.compatibility === 'needs-sync') {
+    push(`Sync template library and rerun: sce auto handoff template-diff --manifest ${manifestCli} --json`);
+  }
+  if (baseline.status === 'error' || (baseline.summary && baseline.summary.portfolio_passed === false)) {
+    push('Rebuild Moqui baseline: sce scene moqui-baseline --json');
+  }
+  if (baselineRegressions.length > 0) {
+    push(
+      `Recover Moqui matrix regressions: ` +
+      `${baselineRegressions.slice(0, 3).map(item => `${item.label}:${item.delta_rate_percent}%`).join(' | ')}`
+    );
+    for (const line of buildMoquiRegressionRecoverySequenceLines({
+      clusterGoalsArg: quoteCliArg(clusterRemediationFile),
+      baselineArg: quoteCliArg(baselineJsonFile),
+      wrapCommands: false,
+      withPeriod: false
+    })) {
+      push(line);
+    }
+  }
+  if (capabilityCoverage.status === 'skipped') {
+    push('Declare `capabilities` in handoff manifest to enable capability matrix coverage gates.');
+  }
+  if (coverageSummary && coverageSummary.passed === false) {
+    push(
+      `Close capability gaps with strict gate: ` +
+      `sce auto handoff run --manifest ${manifestCli} --min-capability-coverage ${coverageSummary.min_required_percent} --json`
+    );
+  }
+  if (coverageSummary && coverageSummary.semantic_passed === false) {
+    push(
+      `Backfill capability ontology semantics and rerun matrix: ` +
+      `sce scene package-ontology-backfill-batch --manifest ${manifestCli} --json`
+    );
+  }
+  if (expectedUnknownCount > 0 || providedUnknownCount > 0) {
+    push(
+      `Normalize capability lexicon gaps with strict audit: ` +
+      `node scripts/moqui-lexicon-audit.js --manifest ${manifestCli} ` +
+      '--template-dir .sce/templates/scene-packages --fail-on-gap --json'
+    );
+  }
+  if (result.remediation_queue && result.remediation_queue.file) {
+    push(
+      `Replay remediation queue: sce auto close-loop-batch ${quoteCliArg(result.remediation_queue.file)} --format lines --json`
+    );
+  }
+
+  return recommendations;
+}
+
+async function buildAutoHandoffCapabilityMatrix(projectPath, options = {}, dependencies = {}) {
+  const {
+    buildAutoHandoffPlan,
+    buildAutoHandoffCapabilityMatrixPolicy,
+    buildAutoHandoffTemplateDiff,
+    buildAutoHandoffMoquiBaselineSnapshot,
+    buildAutoHandoffCapabilityCoverageSnapshot,
+    evaluateAutoHandoffMoquiBaselineGateReasons,
+    evaluateAutoHandoffCapabilityCoverageGateReasons,
+    evaluateAutoHandoffCapabilitySemanticGateReasons,
+    evaluateAutoHandoffCapabilityLexiconGateReasons,
+    normalizeHandoffText,
+    maybeWriteAutoHandoffMoquiRemediationQueue,
+    buildAutoHandoffCapabilityMatrixRecommendations,
+    now = () => new Date().toISOString()
+  } = dependencies;
+
+  const plan = await buildAutoHandoffPlan(projectPath, {
+    manifest: options.manifest,
+    strict: options.strict,
+    strictWarnings: options.strictWarnings
+  });
+
+  const policy = buildAutoHandoffCapabilityMatrixPolicy(options);
+
+  const [templateDiff, moquiBaseline, capabilityCoverage] = await Promise.all([
+    buildAutoHandoffTemplateDiff(projectPath, { handoff: plan.handoff }),
+    buildAutoHandoffMoquiBaselineSnapshot(projectPath),
+    buildAutoHandoffCapabilityCoverageSnapshot(projectPath, plan.handoff, policy)
+  ]);
+
+  const templateSyncReasons = templateDiff.compatibility === 'ready'
+    ? []
+    : [`template-sync:${templateDiff.compatibility}`];
+  const baselineGateReasons = evaluateAutoHandoffMoquiBaselineGateReasons(
+    { require_moqui_baseline: true },
+    moquiBaseline
+  );
+  const capabilityGateReasons = evaluateAutoHandoffCapabilityCoverageGateReasons(
+    policy,
+    capabilityCoverage
+  );
+  const semanticGateReasons = evaluateAutoHandoffCapabilitySemanticGateReasons(
+    policy,
+    capabilityCoverage
+  );
+  const lexiconGateReasons = evaluateAutoHandoffCapabilityLexiconGateReasons(
+    policy,
+    capabilityCoverage
+  );
+  const reasons = [
+    ...templateSyncReasons,
+    ...baselineGateReasons.map(item => `moqui-baseline:${item}`),
+    ...capabilityGateReasons.map(item => `capability-coverage:${item}`),
+    ...semanticGateReasons.map(item => `capability-semantic:${item}`),
+    ...lexiconGateReasons.map(item => `capability-lexicon:${item}`)
+  ];
+
+  const result = {
+    mode: 'auto-handoff-capability-matrix',
+    generated_at: now(),
+    status: reasons.length === 0 ? 'ready' : 'needs-remediation',
+    manifest_path: plan.manifest_path,
+    source_project: plan.source_project || null,
+    handoff: {
+      spec_count: plan.handoff && Number.isFinite(Number(plan.handoff.spec_count))
+        ? Number(plan.handoff.spec_count)
+        : 0,
+      template_count: plan.handoff && Number.isFinite(Number(plan.handoff.template_count))
+        ? Number(plan.handoff.template_count)
+        : 0,
+      capability_count: Array.isArray(plan.handoff && plan.handoff.capabilities)
+        ? plan.handoff.capabilities.length
+        : 0,
+      capability_source: normalizeHandoffText(plan.handoff && plan.handoff.capability_source) || 'manifest',
+      capability_inference: plan.handoff && plan.handoff.capability_inference &&
+        typeof plan.handoff.capability_inference === 'object'
+        ? plan.handoff.capability_inference
+        : {
+          applied: false,
+          inferred_count: 0,
+          inferred_capabilities: [],
+          inferred_from_templates: [],
+          unresolved_template_count: 0,
+          unresolved_templates: []
+        },
+      capabilities: Array.isArray(plan.handoff && plan.handoff.capabilities)
+        ? plan.handoff.capabilities
+        : []
+    },
+    policy,
+    template_diff: templateDiff,
+    moqui_baseline: moquiBaseline,
+    capability_coverage: capabilityCoverage,
+    gates: {
+      passed: reasons.length === 0,
+      reasons,
+      template_sync: {
+        passed: templateSyncReasons.length === 0,
+        reasons: templateSyncReasons
+      },
+      moqui_baseline: {
+        passed: baselineGateReasons.length === 0,
+        reasons: baselineGateReasons
+      },
+      capability_coverage: {
+        passed: capabilityGateReasons.length === 0,
+        reasons: capabilityGateReasons
+      },
+      capability_semantic: {
+        passed: semanticGateReasons.length === 0,
+        reasons: semanticGateReasons
+      },
+      capability_lexicon: {
+        passed: lexiconGateReasons.length === 0,
+        reasons: lexiconGateReasons
+      }
+    },
+    remediation_queue: null,
+    recommendations: []
+  };
+
+  result.remediation_queue = await maybeWriteAutoHandoffMoquiRemediationQueue(
+    projectPath,
+    {
+      moqui_baseline: moquiBaseline,
+      moqui_capability_coverage: capabilityCoverage
+    },
+    options.remediationQueueOut
+  );
+  result.recommendations = buildAutoHandoffCapabilityMatrixRecommendations(result);
+
+  return result;
+}
+
+module.exports = {
+  buildAutoHandoffCapabilityMatrixPolicy,
+  buildAutoHandoffCapabilityMatrixRecommendations,
+  buildAutoHandoffCapabilityMatrix
+};

package/lib/auto/handoff-evidence-review-service.js

@@ -0,0 +1,251 @@
+function buildAutoHandoffEvidenceSnapshot(entry = {}, dependencies = {}) {
+  const {
+    normalizeHandoffText,
+    buildAutoHandoffMoquiCoverageRegressions,
+    normalizeRiskRank
+  } = dependencies;
+  const toNumber = value => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  };
+  const gate = entry && typeof entry.gate === 'object' ? entry.gate : {};
+  const gateActual = gate && typeof gate.actual === 'object' ? gate.actual : {};
+  const ontology = entry && typeof entry.ontology_validation === 'object'
+    ? entry.ontology_validation
+    : {};
+  const ontologyMetrics = ontology && typeof ontology.metrics === 'object'
+    ? ontology.metrics
+    : {};
+  const moquiBaseline = entry && typeof entry.moqui_baseline === 'object'
+    ? entry.moqui_baseline
+    : {};
+  const moquiCompare = moquiBaseline && typeof moquiBaseline.compare === 'object'
+    ? moquiBaseline.compare
+    : {};
+  const moquiMatrixRegressions = buildAutoHandoffMoquiCoverageRegressions(moquiCompare);
+  const scenePackageBatch = entry && typeof entry.scene_package_batch === 'object'
+    ? entry.scene_package_batch
+    : {};
+  const scenePackageBatchSummary = scenePackageBatch && typeof scenePackageBatch.summary === 'object'
+    ? scenePackageBatch.summary
+    : {};
+  const sceneBatchStatus = normalizeHandoffText(scenePackageBatch.status);
+  const sceneBatchPassed = sceneBatchStatus
+    ? (sceneBatchStatus === 'skipped' ? null : sceneBatchStatus === 'passed')
+    : null;
+  const riskLevel = normalizeHandoffText(
+    gateActual.risk_level
+      || (entry && entry.regression ? entry.regression.risk_level : null)
+      || 'high'
+  ) || 'high';
+
+  return {
+    session_id: normalizeHandoffText(entry.session_id),
+    status: normalizeHandoffText(entry.status),
+    merged_at: normalizeHandoffText(entry.merged_at),
+    manifest_path: normalizeHandoffText(entry.manifest_path),
+    gate_passed: gate.passed === true,
+    spec_success_rate_percent: toNumber(gateActual.spec_success_rate_percent),
+    risk_level: `${riskLevel}`.trim().toLowerCase(),
+    risk_level_rank: normalizeRiskRank(riskLevel),
+    failed_goals: toNumber(entry && entry.batch_summary ? entry.batch_summary.failed_goals : null),
+    elapsed_ms: null,
+    ontology_quality_score: toNumber(
+      gateActual.ontology_quality_score !== undefined
+        ? gateActual.ontology_quality_score
+        : ontology.quality_score
+    ),
+    ontology_unmapped_rules: toNumber(
+      gateActual.ontology_business_rule_unmapped !== undefined
+        ? gateActual.ontology_business_rule_unmapped
+        : ontologyMetrics.business_rule_unmapped
+    ),
+    ontology_undecided_decisions: toNumber(
+      gateActual.ontology_decision_undecided !== undefined
+        ? gateActual.ontology_decision_undecided
+        : ontologyMetrics.decision_undecided
+    ),
+    ontology_business_rule_pass_rate_percent: toNumber(ontologyMetrics.business_rule_pass_rate_percent),
+    ontology_decision_resolved_rate_percent: toNumber(ontologyMetrics.decision_resolved_rate_percent),
+    scene_package_batch_status: sceneBatchStatus,
+    scene_package_batch_passed: typeof sceneBatchPassed === 'boolean' ? sceneBatchPassed : null,
+    scene_package_batch_failure_count: toNumber(
+      scenePackageBatchSummary.batch_gate_failure_count !== undefined
+        ? scenePackageBatchSummary.batch_gate_failure_count
+        : scenePackageBatchSummary.failed
+    ),
+    capability_coverage_percent: toNumber(
+      entry &&
+      entry.capability_coverage &&
+      entry.capability_coverage.summary
+        ? entry.capability_coverage.summary.coverage_percent
+        : null
+    ),
+    capability_coverage_passed: Boolean(
+      entry &&
+      entry.capability_coverage &&
+      entry.capability_coverage.summary &&
+      entry.capability_coverage.summary.passed === true
+    ),
+    moqui_matrix_regression_count: moquiMatrixRegressions.length,
+    generated_at: normalizeHandoffText(entry.merged_at)
+  };
+}
+
+function buildAutoHandoffEvidenceStatusCounts(entries = []) {
+  const counts = {
+    completed: 0,
+    failed: 0,
+    dry_run: 0,
+    running: 0,
+    other: 0
+  };
+  entries.forEach(entry => {
+    const status = `${entry && entry.status ? entry.status : ''}`.trim().toLowerCase();
+    if (status === 'completed') {
+      counts.completed += 1;
+    } else if (status === 'failed') {
+      counts.failed += 1;
+    } else if (status === 'dry-run' || status === 'dry_run') {
+      counts.dry_run += 1;
+    } else if (status === 'running') {
+      counts.running += 1;
+    } else {
+      counts.other += 1;
+    }
+  });
+  return counts;
+}
+
+async function resolveAutoHandoffReleaseDraftContext(projectPath, options = {}, dependencies = {}) {
+  const { fs, pathModule } = dependencies;
+  let packageVersion = null;
+  try {
+    const packagePayload = await fs.readJson(pathModule.join(projectPath, 'package.json'));
+    if (packagePayload && typeof packagePayload.version === 'string' && packagePayload.version.trim()) {
+      packageVersion = packagePayload.version.trim();
+    }
+  } catch (_error) {
+    packageVersion = null;
+  }
+  return {
+    version: dependencies.normalizeHandoffReleaseVersion(options.releaseVersion, packageVersion || '0.0.0'),
+    releaseDate: dependencies.normalizeHandoffReleaseDate(options.releaseDate)
+  };
+}
+
+async function buildAutoHandoffEvidenceReviewReport(projectPath, options = {}, dependencies = {}) {
+  const {
+    loadAutoHandoffReleaseEvidence,
+    normalizeHandoffSessionQuery,
+    normalizeHandoffEvidenceWindow,
+    normalizeHandoffText,
+    buildAutoHandoffEvidenceSnapshot,
+    buildAutoHandoffRegressionComparison,
+    buildAutoHandoffRegressionWindowTrend,
+    buildAutoHandoffRegressionAggregates,
+    buildAutoHandoffRegressionRiskLayers,
+    buildAutoHandoffEvidenceStatusCounts,
+    buildAutoGovernanceStats,
+    buildAutoHandoffRegressionRecommendations,
+    now = () => new Date().toISOString()
+  } = dependencies;
+
+  const releaseEvidence = await loadAutoHandoffReleaseEvidence(projectPath, options.file);
+  if (releaseEvidence.sessions.length === 0) {
+    throw new Error(`no release evidence sessions found: ${releaseEvidence.file}`);
+  }
+
+  const query = normalizeHandoffSessionQuery(options.sessionId);
+  const windowSize = normalizeHandoffEvidenceWindow(options.window);
+  let currentIndex = 0;
+  if (query !== 'latest') {
+    currentIndex = releaseEvidence.sessions.findIndex(item => normalizeHandoffText(item.session_id) === query);
+    if (currentIndex < 0) {
+      throw new Error(`release evidence session not found: ${query}`);
+    }
+  }
+
+  const selectedEntries = releaseEvidence.sessions.slice(currentIndex, currentIndex + windowSize);
+  const series = selectedEntries.map(item => buildAutoHandoffEvidenceSnapshot(item));
+  const currentSnapshot = series[0];
+  const previousSnapshot = series[1] || null;
+  const comparison = previousSnapshot
+    ? buildAutoHandoffRegressionComparison(currentSnapshot, previousSnapshot)
+    : {
+      trend: 'baseline',
+      delta: {
+        spec_success_rate_percent: null,
+        risk_level_rank: null,
+        failed_goals: null,
+        elapsed_ms: null,
+        ontology_quality_score: null,
+        ontology_unmapped_rules: null,
+        ontology_undecided_decisions: null,
+        ontology_business_rule_pass_rate_percent: null,
+        ontology_decision_resolved_rate_percent: null,
+        scene_package_batch_failure_count: null
+      }
+    };
+  const windowTrend = buildAutoHandoffRegressionWindowTrend(series);
+  const aggregates = buildAutoHandoffRegressionAggregates(series);
+  const riskLayers = buildAutoHandoffRegressionRiskLayers(series);
+  const statusCounts = buildAutoHandoffEvidenceStatusCounts(selectedEntries);
+  const gatePassCount = selectedEntries.filter(item => item && item.gate && item.gate.passed === true).length;
+  const gatePassRate = selectedEntries.length > 0
+    ? Number(((gatePassCount / selectedEntries.length) * 100).toFixed(2))
+    : null;
+  let governanceSnapshot = null;
+  try {
+    const governanceStats = await buildAutoGovernanceStats(projectPath, {});
+    governanceSnapshot = {
+      mode: governanceStats && governanceStats.mode ? governanceStats.mode : 'auto-governance-stats',
+      generated_at: governanceStats && governanceStats.generated_at ? governanceStats.generated_at : now(),
+      criteria: governanceStats && governanceStats.criteria ? governanceStats.criteria : null,
+      totals: governanceStats && governanceStats.totals ? governanceStats.totals : null,
+      health: governanceStats && governanceStats.health ? governanceStats.health : null
+    };
+  } catch (error) {
+    governanceSnapshot = {
+      mode: 'auto-governance-stats',
+      generated_at: now(),
+      error: error.message
+    };
+  }
+
+  const payload = {
+    mode: 'auto-handoff-evidence-review',
+    generated_at: now(),
+    evidence_file: releaseEvidence.file,
+    release_evidence_updated_at: normalizeHandoffText(releaseEvidence.payload.updated_at),
+    session_query: query,
+    current: currentSnapshot,
+    current_overview: selectedEntries[0] || null,
+    previous: previousSnapshot,
+    trend: comparison.trend,
+    delta: comparison.delta,
+    window: {
+      requested: windowSize,
+      actual: series.length
+    },
+    series,
+    window_trend: windowTrend,
+    aggregates: {
+      ...aggregates,
+      status_counts: statusCounts,
+      gate_pass_rate_percent: gatePassRate
+    },
+    risk_layers: riskLayers,
+    governance_snapshot: governanceSnapshot,
+    recommendations: []
+  };
+  payload.recommendations = buildAutoHandoffRegressionRecommendations(payload);
+  return payload;
+}
+
+module.exports = {
+  buildAutoHandoffEvidenceSnapshot,
+  buildAutoHandoffEvidenceStatusCounts,
+  resolveAutoHandoffReleaseDraftContext,
+  buildAutoHandoffEvidenceReviewReport
+};