scene-capability-engine 3.3.22 → 3.3.24

package/lib/spec/domain-modeling.js

@@ -0,0 +1,439 @@
+const fs = require('fs-extra');
+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 DOMAIN_CHAIN_API_VERSION = 'sce.problem-domain-chain/v0.1';
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function resolveSpecPaths(projectPath, specId) {
+  const specPath = path.join(projectPath, '.sce', 'specs', specId);
+  return {
+    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)
+  };
+}
+
+function buildProblemDomainMindMap(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 primaryFlow = normalizeText(options.primaryFlow) || 'TBD: define core user/business flow';
+  const verificationPlan = normalizeText(options.verificationPlan) || 'TBD: define validation and rollback criteria';
+
+  return `# Problem Domain Mind Map
+
+> Mandatory artifact: use this map to expand the problem domain before implementation.
+> Policy: after two failed fix rounds, diagnostics must be added before the next patch round.
+
+## Root Problem
+
+- Scene: \`${sceneId}\`
+- Spec: \`${specId}\`
+- Problem Statement: ${problemStatement}
+- Primary Flow: ${primaryFlow}
+
+## Domain Mind Map
+
+\`\`\`mermaid
+mindmap
+  root((${specId}))
+    Problem
+      Symptom
+      Root Cause Hypothesis
+      Constraints
+    Ontology
+      Entity
+      Relation
+      Business Rule
+      Decision Policy
+      Execution Flow
+    Stakeholders
+      User
+      Operator
+      Maintainer
+    Risk
+      Wrong Direction
+      Data Integrity
+      Security
+      Rollback
+    Validation
+      Test Evidence
+      Runtime Signal
+      Gate Criteria
+\`\`\`
+
+## Layered Exploration Chain
+
+1. Clarify symptom scope and affected boundaries.
+2. Enumerate entities, relations, and rule constraints.
+3. Identify decision points and execution paths.
+4. Produce candidate fixes and risk tradeoffs.
+5. Define verification path and measurable acceptance.
+
+## Correction Loop
+
+- Expected Wrong-Direction Signals:
+  - requirement drift
+  - ontology mismatch
+  - repeated failed remediation
+- Correction Actions:
+  - update this map
+  - add debug evidence
+  - adjust scene-spec contract before coding
+
+## Verification Plan
+
+- ${verificationPlan}
+`;
+}
+
+function buildSceneSpec(specId, options = {}) {
+  const sceneId = normalizeText(options.sceneId) || `scene.${specId.replace(/[^a-zA-Z0-9]+/g, '-').toLowerCase()}`;
+  const problemStatement = normalizeText(options.problemStatement) || 'TBD';
+  const primaryFlow = normalizeText(options.primaryFlow) || 'TBD';
+  const verificationPlan = normalizeText(options.verificationPlan) || 'TBD';
+
+  return `# Scene Spec
+
+> Mandatory artifact: scene-oriented contract for implementation and gating.
+
+## Scene Definition
+
+- Scene ID: \`${sceneId}\`
+- Spec ID: \`${specId}\`
+- Objective: ${problemStatement}
+- Primary Flow: ${primaryFlow}
+
+## Scope & Boundaries
+
+- In Scope:
+  - core scene behavior
+  - required integrations
+- Out of Scope:
+  - unrelated legacy refactors
+  - uncontrolled workaround paths
+
+## Ontology Coverage
+
+| Layer | Required Mapping |
+| --- | --- |
+| Entity | list key domain entities |
+| Relation | list key relations |
+| Business Rule | list enforceable rules |
+| Decision Policy | list decision points |
+| Execution Flow | list end-to-end action chain |
+
+## Decision & Execution Path
+
+1. Trigger condition and entry point.
+2. Decision policy branch(es).
+3. Service/tool execution sequence.
+4. Expected outputs and side effects.
+5. Failure path and rollback criteria.
+
+## Acceptance & Gate
+
+- Functional acceptance: define testable behaviors.
+- Technical acceptance: define gate/test requirements.
+- Verification Plan: ${verificationPlan}
+`;
+}
+
+function buildProblemDomainChain(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 primaryFlow = normalizeText(options.primaryFlow) || 'TBD: define core user/business flow';
+  const verificationPlan = normalizeText(options.verificationPlan) || 'TBD: define validation and rollback criteria';
+  const now = new Date().toISOString();
+
+  return {
+    api_version: DOMAIN_CHAIN_API_VERSION,
+    generated_at: now,
+    scene_id: sceneId,
+    spec_id: specId,
+    problem: {
+      statement: problemStatement,
+      scope: 'TBD: define boundary and excluded domains',
+      symptom: 'TBD: observable symptom and impact'
+    },
+    ontology: {
+      entity: ['TBD: primary entity'],
+      relation: ['TBD: key relation'],
+      business_rule: ['TBD: enforceable business rule'],
+      decision_policy: ['TBD: decision condition and policy'],
+      execution_flow: ['TBD: action chain and side effects']
+    },
+    hypotheses: [
+      {
+        id: 'H1',
+        statement: 'TBD: root-cause hypothesis',
+        evidence: ['TBD: evidence or signal'],
+        confidence: 'low'
+      }
+    ],
+    risks: [
+      {
+        id: 'R1',
+        type: 'wrong-direction',
+        statement: 'TBD: direction drift risk',
+        mitigation: 'TBD: correction checkpoint'
+      }
+    ],
+    decision_execution_path: [
+      {
+        step: 1,
+        action: 'entry',
+        decision: 'TBD: trigger condition',
+        expected_result: 'TBD: expected output'
+      },
+      {
+        step: 2,
+        action: 'route',
+        decision: 'TBD: policy branch',
+        expected_result: 'TBD: branch result'
+      },
+      {
+        step: 3,
+        action: 'execute',
+        decision: 'TBD: execution rule',
+        expected_result: 'TBD: side effect and data change'
+      }
+    ],
+    correction_loop: {
+      triggers: [
+        'gate failure',
+        'ontology mismatch',
+        'two failed fix rounds'
+      ],
+      actions: [
+        'refresh domain map',
+        'attach debug evidence',
+        'rebuild scene spec contract'
+      ]
+    },
+    verification: {
+      plan: verificationPlan,
+      gates: [
+        'spec-gate',
+        'tests',
+        'release preflight'
+      ]
+    }
+  };
+}
+
+function validateProblemDomainMapContent(content = '') {
+  const checks = {
+    hasRootProblem: /##\s+Root Problem/i.test(content),
+    hasMindMapBlock: /```mermaid[\s\S]*mindmap/i.test(content),
+    hasLayeredExplorationChain: /##\s+Layered Exploration Chain/i.test(content),
+    hasCorrectionLoop: /##\s+Correction Loop/i.test(content)
+  };
+  const passed = Object.values(checks).every(Boolean);
+  return { passed, checks };
+}
+
+function validateSceneSpecContent(content = '') {
+  const checks = {
+    hasSceneDefinition: /##\s+Scene Definition/i.test(content),
+    hasOntologyCoverage: /##\s+Ontology Coverage/i.test(content),
+    hasDecisionExecutionPath: /##\s+Decision & Execution Path/i.test(content),
+    hasAcceptanceGate: /##\s+Acceptance & Gate/i.test(content)
+  };
+  const passed = Object.values(checks).every(Boolean);
+  return { passed, checks };
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function hasNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.some((item) => isNonEmptyString(item));
+}
+
+function validateProblemDomainChainPayload(payload = {}, specId = '') {
+  const checks = {
+    apiVersion: isNonEmptyString(payload.api_version),
+    sceneId: isNonEmptyString(payload.scene_id),
+    specId: isNonEmptyString(payload.spec_id) && (!specId || payload.spec_id === specId),
+    problemStatement: isNonEmptyString(payload?.problem?.statement),
+    ontologyEntity: hasNonEmptyStringArray(payload?.ontology?.entity),
+    ontologyRelation: hasNonEmptyStringArray(payload?.ontology?.relation),
+    ontologyBusinessRule: hasNonEmptyStringArray(payload?.ontology?.business_rule),
+    ontologyDecisionPolicy: hasNonEmptyStringArray(payload?.ontology?.decision_policy),
+    ontologyExecutionFlow: hasNonEmptyStringArray(payload?.ontology?.execution_flow),
+    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,
+    hasCorrectionTriggers: hasNonEmptyStringArray(payload?.correction_loop?.triggers),
+    hasCorrectionActions: hasNonEmptyStringArray(payload?.correction_loop?.actions),
+    hasVerificationGates: hasNonEmptyStringArray(payload?.verification?.gates)
+  };
+  return {
+    passed: Object.values(checks).every(Boolean),
+    checks
+  };
+}
+
+async function ensureSpecDomainArtifacts(projectPath, specId, options = {}) {
+  const fileSystem = options.fileSystem || fs;
+  const dryRun = options.dryRun === true;
+  const force = options.force === true;
+
+  const paths = resolveSpecPaths(projectPath, specId);
+  const domainMapContent = buildProblemDomainMindMap(specId, options);
+  const sceneSpecContent = buildSceneSpec(specId, options);
+  const domainChainPayload = buildProblemDomainChain(specId, options);
+
+  const created = {
+    domain_map: false,
+    scene_spec: false,
+    domain_chain: false
+  };
+
+  if (!dryRun) {
+    await fileSystem.ensureDir(path.dirname(paths.domainMapPath));
+
+    const hasDomainMap = await fileSystem.pathExists(paths.domainMapPath);
+    if (force || !hasDomainMap) {
+      await fileSystem.writeFile(paths.domainMapPath, domainMapContent, 'utf8');
+      created.domain_map = true;
+    }
+
+    const hasSceneSpec = await fileSystem.pathExists(paths.sceneSpecPath);
+    if (force || !hasSceneSpec) {
+      await fileSystem.writeFile(paths.sceneSpecPath, sceneSpecContent, 'utf8');
+      created.scene_spec = true;
+    }
+
+    const hasDomainChain = await fileSystem.pathExists(paths.domainChainPath);
+    if (force || !hasDomainChain) {
+      await fileSystem.writeJson(paths.domainChainPath, domainChainPayload, { spaces: 2 });
+      created.domain_chain = true;
+    }
+  } else {
+    created.domain_map = true;
+    created.scene_spec = true;
+    created.domain_chain = true;
+  }
+
+  return {
+    paths: {
+      domain_map: paths.domainMapPath,
+      scene_spec: paths.sceneSpecPath,
+      domain_chain: paths.domainChainPath
+    },
+    created,
+    preview: {
+      domain_map: domainMapContent,
+      scene_spec: sceneSpecContent,
+      domain_chain: domainChainPayload
+    }
+  };
+}
+
+async function validateSpecDomainArtifacts(projectPath, specId, fileSystem = fs) {
+  const paths = resolveSpecPaths(projectPath, specId);
+  const warnings = [];
+  const details = {
+    domain_map: {
+      path: paths.domainMapPath,
+      exists: false,
+      checks: {}
+    },
+    scene_spec: {
+      path: paths.sceneSpecPath,
+      exists: false,
+      checks: {}
+    },
+    domain_chain: {
+      path: paths.domainChainPath,
+      exists: false,
+      checks: {}
+    }
+  };
+
+  let passedChecks = 0;
+  const totalChecks = 3;
+
+  const hasDomainMap = await fileSystem.pathExists(paths.domainMapPath);
+  details.domain_map.exists = hasDomainMap;
+  if (!hasDomainMap) {
+    warnings.push(`Missing required artifact: ${DOMAIN_MAP_RELATIVE_PATH}`);
+  } else {
+    const content = await fileSystem.readFile(paths.domainMapPath, 'utf8');
+    const evaluation = validateProblemDomainMapContent(content);
+    details.domain_map.checks = evaluation.checks;
+    if (evaluation.passed) {
+      passedChecks += 1;
+    } else {
+      warnings.push(`Invalid ${DOMAIN_MAP_RELATIVE_PATH}: missing mandatory sections`);
+    }
+  }
+
+  const hasSceneSpec = await fileSystem.pathExists(paths.sceneSpecPath);
+  details.scene_spec.exists = hasSceneSpec;
+  if (!hasSceneSpec) {
+    warnings.push(`Missing required artifact: ${SCENE_SPEC_RELATIVE_PATH}`);
+  } else {
+    const content = await fileSystem.readFile(paths.sceneSpecPath, 'utf8');
+    const evaluation = validateSceneSpecContent(content);
+    details.scene_spec.checks = evaluation.checks;
+    if (evaluation.passed) {
+      passedChecks += 1;
+    } else {
+      warnings.push(`Invalid ${SCENE_SPEC_RELATIVE_PATH}: missing mandatory sections`);
+    }
+  }
+
+  const hasDomainChain = await fileSystem.pathExists(paths.domainChainPath);
+  details.domain_chain.exists = hasDomainChain;
+  if (!hasDomainChain) {
+    warnings.push(`Missing required artifact: ${DOMAIN_CHAIN_RELATIVE_PATH}`);
+  } else {
+    let payload = null;
+    try {
+      payload = await fileSystem.readJson(paths.domainChainPath);
+    } catch (error) {
+      warnings.push(`Invalid ${DOMAIN_CHAIN_RELATIVE_PATH}: malformed JSON (${error.message})`);
+    }
+    if (payload) {
+      const evaluation = validateProblemDomainChainPayload(payload, specId);
+      details.domain_chain.checks = evaluation.checks;
+      if (evaluation.passed) {
+        passedChecks += 1;
+      } else {
+        warnings.push(`Invalid ${DOMAIN_CHAIN_RELATIVE_PATH}: missing mandatory chain fields`);
+      }
+    }
+  }
+
+  return {
+    passed: passedChecks === totalChecks,
+    ratio: passedChecks / totalChecks,
+    details,
+    warnings
+  };
+}
+
+module.exports = {
+  DOMAIN_MAP_RELATIVE_PATH,
+  SCENE_SPEC_RELATIVE_PATH,
+  DOMAIN_CHAIN_RELATIVE_PATH,
+  DOMAIN_CHAIN_API_VERSION,
+  buildProblemDomainMindMap,
+  buildSceneSpec,
+  buildProblemDomainChain,
+  ensureSpecDomainArtifacts,
+  validateSpecDomainArtifacts
+};

package/lib/spec-gate/policy/default-policy.js

@@ -11,6 +11,7 @@ const DEFAULT_GATE_POLICY = {
     mandatory: { enabled: true, weight: 30, hard_fail: true },
     tests: { enabled: true, weight: 25, hard_fail: true },
     docs: { enabled: true, weight: 15, hard_fail: false },
+    domain_scene_modeling: { enabled: true, weight: 25, hard_fail: true },
     config_consistency: { enabled: true, weight: 15, hard_fail: false },
     traceability: { enabled: true, weight: 15, hard_fail: false }
   }

package/lib/spec-gate/rules/default-rules.js

@@ -1,6 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const docsCommand = require('../../commands/docs');
+const { validateSpecDomainArtifacts } = require('../../spec/domain-modeling');
 
 function createDefaultRules(projectPath = process.cwd()) {
   return [
@@ -75,6 +76,13 @@ function createDefaultRules(projectPath = process.cwd()) {
         };
       }
     },
+    {
+      id: 'domain_scene_modeling',
+      description: 'Verify mandatory problem-domain mind map and scene-spec artifacts',
+      async execute(context) {
+        return validateSpecDomainArtifacts(projectPath, context.specId, fs);
+      }
+    },
     {
       id: 'config_consistency',
       description: 'Verify project-level sce config baseline exists',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.22",
+  "version": "3.3.24",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -69,11 +69,12 @@
     "report:release-ops-weekly": "node scripts/release-ops-weekly-summary.js --json",
     "gate:release-ops-weekly": "node scripts/release-weekly-ops-gate.js",
     "gate:errorbook-release": "node scripts/errorbook-release-gate.js --fail-on-block",
+    "gate:errorbook-registry-health": "node scripts/errorbook-registry-health-gate.js",
     "gate:git-managed": "node scripts/git-managed-gate.js --fail-on-violation",
     "gate:release-asset-integrity": "node scripts/release-asset-integrity-check.js",
     "report:release-risk-remediation": "node scripts/release-risk-remediation-bundle.js --json",
     "report:moqui-core-regression": "node scripts/moqui-core-regression-suite.js --json",
-    "prepublishOnly": "npm run test:full && npm run test:skip-audit && npm run test:sce-tracking && npm run test:brand-consistency && npm run gate:git-managed && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
+    "prepublishOnly": "npm run test:full && npm run test:skip-audit && npm run test:sce-tracking && npm run test:brand-consistency && npm run gate:git-managed && npm run gate:errorbook-registry-health && npm run gate:errorbook-release && npm run report:interactive-governance -- --fail-on-alert",
     "publish:manual": "npm publish --access public",
     "install-global": "npm install -g .",
     "uninstall-global": "npm uninstall -g scene-capability-engine"

package/template/.sce/config/errorbook-registry.json

@@ -0,0 +1,13 @@
+{
+  "enabled": true,
+  "search_mode": "remote",
+  "cache_file": ".sce/errorbook/registry-cache.json",
+  "sources": [
+    {
+      "name": "central",
+      "enabled": true,
+      "url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.json",
+      "index_url": "https://raw.githubusercontent.com/heguangyong/sce-errorbook-registry/main/registry/errorbook-registry.index.json"
+    }
+  ]
+}

package/template/.sce/steering/CORE_PRINCIPLES.md

@@ -72,6 +72,17 @@
 
 **目标**: 用户说"开始执行 Spec XX"，AI 自主完成所有任务交付功能
 
+### 4.2 强制默认自主推进（无二次确认）⚡
+
+**核心**: 默认执行策略必须是“自主闭环推进”，不是“每步等待确认”
+
+**默认行为**:
+1) 接到任务后直接进入：分析 → 修改 → 测试 → 修复 → 提交 → 推送（若已配置远端）  
+2) 非阻断性问题（可自行定位/修复）不得暂停等待用户二次确认  
+3) 仅在以下情况允许中断并请求用户介入：外部权限缺失、不可恢复致命错误、生产高风险变更、业务目标冲突
+
+**强制要求**: 不得以“先等你确认再继续”替代执行；未形成可验证结果前不得提前结束
+
 ### 5. 上下文管控
 
 **主动管控避免 token 耗尽**
@@ -158,6 +169,8 @@
 
 **复杂问题定位方法**: 优先使用 debug 日志与可观测信号定位（输入、输出、关键分支、异常栈、上下文参数），先还原执行路径再下结论
 
+**两轮失败强制调试规则**: 同一问题连续 2 轮修复仍未达到目标验证（测试/门禁/验收）时，必须切换到 debug 定位模式；先补充结构化 debug 日志与关键观测点，复现并固化失败证据，再进入第 3 轮修复。❌ 禁止在未接入调试证据前继续盲改
+
 **修复后清理要求**: 问题修复并验证通过后，必须清理临时 debug 日志、临时埋点、一次性脚本和调试开关；需要长期保留的日志必须转为可配置观测项且默认关闭
 
 **允许的临时措施**: 仅在生产止血场景可临时绕行，但必须同时给出根因修复任务、回滚条件和截止时间
@@ -189,6 +202,22 @@
 
 **目标**: 保证跨 Agent 连续性、可追溯历史、上下文可控，避免因 Agent session 长短差异导致上下文漂移
 
+### 14. 问题域思维导图 + 场景化 Spec 强制原则 🧠
+
+**核心**: Spec 推进必须先完成“问题域思维导图”与“场景化 Spec 契约”，再进入实现与修复闭环
+
+**硬规则**:
+1) 每个 Spec 必须具备：
+   - `.sce/specs/<spec>/custom/problem-domain-map.md`
+   - `.sce/specs/<spec>/custom/scene-spec.md`
+   - `.sce/specs/<spec>/custom/problem-domain-chain.json`
+2) `problem-domain-map` 必须包含：Root Problem、Mind Map、Layered Exploration Chain、Correction Loop
+3) `scene-spec` 必须包含：Scene Definition、Ontology Coverage、Decision & Execution Path、Acceptance & Gate
+4) `problem-domain-chain.json` 必须包含可机读思维链：problem/ontology/hypotheses/risks/decision_execution_path/correction_loop/verification
+5) 默认门禁强制校验上述结构，缺失即 `no-go`
+
+**目标**: 用全局问题域视角 + 场景契约约束，减少方向性错误与盲改，提升纠偏效率
+
 ---
 
-v18.0 | 2026-02-27 | 强化根因修复与临时兜底发布门禁原则
+v21.0 | 2026-03-01 | 强化“强制默认自主推进（无二次确认）”执行基线