scene-capability-engine 3.3.10 → 3.3.12

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.12] - 2026-02-25
+
+### Changed
+- Strengthened steering baseline for root-cause defect handling:
+  - Added explicit rule: bug fixing must prioritize root-cause remediation, not workaround-style bypass.
+  - Added explicit complex-issue debugging method: prefer debug logs and observability signals (inputs/outputs/branches/stack/context) to reconstruct execution path before conclusion.
+- Standardized ontology analysis baseline in steering as a unified "four layers + one chain" model:
+  - Entity model
+  - Relation graph
+  - Business rule
+  - Decision logic
+  - Action/lineage execution chain
+- Synced the same steering enhancements to both runtime project steering and template steering:
+  - `.sce/steering/CORE_PRINCIPLES.md`
+  - `template/.sce/steering/CORE_PRINCIPLES.md`
+
+## [3.3.11] - 2026-02-24
+
+### Added
+- Workspace tracking audit for deterministic `.sce` fixture governance:
+  - New command: `sce workspace tracking-audit` (`--json`, `--no-strict`)
+  - New CI script: `node scripts/check-sce-tracking.js`
+  - New npm alias: `npm run test:sce-tracking`
+  - New audit helper: `lib/workspace/sce-tracking-audit.js`
+  - New unit coverage: `tests/unit/workspace/sce-tracking-audit.test.js`
+
+### Changed
+- `sce workspace legacy-migrate` now requires explicit `--confirm` for non-dry-run execution.
+- `prepublishOnly` now includes `test:sce-tracking` to prevent missing tracked `.sce` fixture assets before publish.
+
+### Fixed
+- Added integration coverage to ensure legacy migration remains a strictly manual two-step flow (`--dry-run` then `--confirm`).
+
 ## [3.3.10] - 2026-02-24
 
 ### Fixed

package/bin/scene-capability-engine.js

@@ -25,6 +25,7 @@ const {
   findLegacyKiroDirectories,
   migrateLegacyKiroDirectories,
 } = require('../lib/workspace/legacy-kiro-migrator');
+const { auditSceTracking } = require('../lib/workspace/sce-tracking-audit');
 
 const i18n = getI18n();
 const t = (key, params) => i18n.t(key, params);
@@ -656,9 +657,28 @@ workspaceCmd
   .command('legacy-migrate')
   .description('Migrate legacy .kiro directories to .sce')
   .option('--dry-run', 'Preview migration actions without writing changes')
+  .option('--confirm', 'Confirm manual migration execution (required for non-dry-run migration)')
   .option('--max-depth <n>', 'Maximum recursive scan depth', parseInt)
   .option('--json', 'Output in JSON format')
   .action(async (options) => {
+    if (!options.dryRun && options.confirm !== true) {
+      const message = 'Manual confirmation required: rerun with --confirm (or use --dry-run first).';
+      if (options.json) {
+        console.log(JSON.stringify({
+          success: false,
+          mode: 'workspace-legacy-migrate',
+          error: message,
+          hint: 'sce workspace legacy-migrate --dry-run --json'
+        }, null, 2));
+      } else {
+        console.error(chalk.red(message));
+        console.error(chalk.gray('Preview first:  sce workspace legacy-migrate --dry-run'));
+        console.error(chalk.gray('Apply manually: sce workspace legacy-migrate --confirm'));
+      }
+      process.exitCode = 2;
+      return;
+    }
+
     const workspaceRoot = process.cwd();
     const report = await migrateLegacyKiroDirectories(workspaceRoot, {
       dryRun: options.dryRun === true,
@@ -686,6 +706,41 @@ workspaceCmd
     console.log(chalk.gray(`Conflict files: ${report.conflict_files}`));
   });
 
+workspaceCmd
+  .command('tracking-audit')
+  .description('Audit tracked .sce assets required for deterministic CI/release behavior')
+  .option('--json', 'Output in JSON format')
+  .option('--no-strict', 'Do not fail process when audit reports violations')
+  .action(async (options) => {
+    const report = auditSceTracking(process.cwd());
+
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (report.passed) {
+      console.log(chalk.green('✓ SCE tracking audit passed.'));
+      console.log(chalk.gray(`Fixture tracked specs: ${report.summary.fixture_spec_files}`));
+      console.log(chalk.gray(`Fixture tracked templates: ${report.summary.fixture_template_files}`));
+    } else {
+      console.log(chalk.red('✖ SCE tracking audit failed.'));
+      if (report.missing_required_files.length > 0) {
+        console.log(chalk.yellow('Missing required tracked files:'));
+        for (const filePath of report.missing_required_files) {
+          console.log(chalk.gray(`  - ${filePath}`));
+        }
+      }
+      if (report.fixture.disallowed_tracked_files.length > 0) {
+        console.log(chalk.yellow('Disallowed tracked fixture runtime files:'));
+        for (const filePath of report.fixture.disallowed_tracked_files) {
+          console.log(chalk.gray(`  - ${filePath}`));
+        }
+      }
+    }
+
+    if (!report.passed && options.strict !== false) {
+      process.exitCode = 1;
+    }
+  });
+
 // Environment configuration management commands
 const envCommand = require('../lib/commands/env');
 
@@ -900,7 +955,7 @@ async function updateProjectConfig(projectName) {
       ));
       console.error(chalk.yellow('SCE blocks all non-migration commands until migration is completed.'));
       console.error(chalk.gray('Review first:  sce workspace legacy-migrate --dry-run'));
-      console.error(chalk.gray('Apply manually: sce workspace legacy-migrate'));
+      console.error(chalk.gray('Apply manually: sce workspace legacy-migrate --confirm'));
       process.exit(2);
     }
   }

package/docs/command-reference.md

@@ -225,11 +225,16 @@ sce workspace legacy-scan
 sce workspace legacy-scan --max-depth 8 --json
 
 # Migrate legacy .kiro directories to .sce (safe merge when .sce already exists)
-sce workspace legacy-migrate
+# Non-dry-run migration now requires explicit manual confirmation.
+sce workspace legacy-migrate --confirm
 sce workspace legacy-migrate --dry-run --json
 # Recommended: always run dry-run first, then execute manual migration
 # sce workspace legacy-migrate --dry-run
-# sce workspace legacy-migrate
+# sce workspace legacy-migrate --confirm
+
+# Audit tracked .sce assets required for deterministic CI/release behavior
+sce workspace tracking-audit
+sce workspace tracking-audit --json
 
 # Safety guardrail (default):
 # If legacy .kiro directories exist, sce blocks non-migration commands

package/lib/workspace/sce-tracking-audit.js

@@ -0,0 +1,74 @@
+const { execSync } = require('child_process');
+
+const FIXTURE_ROOT = 'tests/fixtures/moqui-core-regression/workspace/.sce';
+const REQUIRED_TRACKED_FILES = [
+  `${FIXTURE_ROOT}/specs/60-10-moqui-core-order-query/custom/scene-package.json`,
+  `${FIXTURE_ROOT}/specs/60-10-moqui-core-order-query/custom/scene.yaml`,
+  `${FIXTURE_ROOT}/templates/scene-packages/kse.scene--erp-order-query-read--0.1.0/scene-package.json`,
+];
+const DISALLOWED_TRACKED_PREFIXES = [
+  `${FIXTURE_ROOT}/reports/`,
+  `${FIXTURE_ROOT}/auto/`,
+];
+
+function defaultGetTrackedFiles(repoRoot) {
+  const output = execSync('git ls-files', {
+    cwd: repoRoot,
+    encoding: 'utf8'
+  });
+  return output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function auditSceTracking(repoRoot = process.cwd(), dependencies = {}) {
+  const getTrackedFiles = dependencies.getTrackedFiles || defaultGetTrackedFiles;
+  const trackedFiles = getTrackedFiles(repoRoot)
+    .map((filePath) => `${filePath}`.replace(/\\/g, '/'));
+  const trackedSet = new Set(trackedFiles);
+
+  const missingRequiredFiles = REQUIRED_TRACKED_FILES.filter((filePath) => !trackedSet.has(filePath));
+  const fixtureTrackedFiles = trackedFiles.filter((filePath) => filePath.startsWith(`${FIXTURE_ROOT}/`));
+  const fixtureSpecTrackedFiles = fixtureTrackedFiles.filter((filePath) => filePath.startsWith(`${FIXTURE_ROOT}/specs/`));
+  const fixtureTemplateTrackedFiles = fixtureTrackedFiles.filter((filePath) => filePath.startsWith(`${FIXTURE_ROOT}/templates/`));
+  const disallowedTrackedFiles = fixtureTrackedFiles.filter((filePath) =>
+    DISALLOWED_TRACKED_PREFIXES.some((prefix) => filePath.startsWith(prefix))
+  );
+
+  const summary = {
+    missing_required_files: missingRequiredFiles.length,
+    fixture_spec_files: fixtureSpecTrackedFiles.length,
+    fixture_template_files: fixtureTemplateTrackedFiles.length,
+    disallowed_fixture_files: disallowedTrackedFiles.length
+  };
+
+  const passed =
+    missingRequiredFiles.length === 0 &&
+    fixtureSpecTrackedFiles.length > 0 &&
+    fixtureTemplateTrackedFiles.length > 0 &&
+    disallowedTrackedFiles.length === 0;
+
+  return {
+    mode: 'sce-tracking-audit',
+    passed,
+    root: repoRoot,
+    required_files: REQUIRED_TRACKED_FILES,
+    missing_required_files: missingRequiredFiles,
+    fixture: {
+      root: FIXTURE_ROOT,
+      tracked_total: fixtureTrackedFiles.length,
+      tracked_specs: fixtureSpecTrackedFiles,
+      tracked_templates: fixtureTemplateTrackedFiles,
+      disallowed_tracked_files: disallowedTrackedFiles
+    },
+    summary
+  };
+}
+
+module.exports = {
+  FIXTURE_ROOT,
+  REQUIRED_TRACKED_FILES,
+  DISALLOWED_TRACKED_PREFIXES,
+  auditSceTracking
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.10",
+  "version": "3.3.12",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -34,6 +34,7 @@
     "test:interactive-loop-smoke": "node scripts/interactive-loop-smoke.js --json",
     "test:interactive-flow-smoke": "node scripts/interactive-flow-smoke.js --json",
     "test:skip-audit": "node scripts/check-skip-allowlist.js",
+    "test:sce-tracking": "node scripts/check-sce-tracking.js",
     "test:brand-consistency": "node scripts/check-branding-consistency.js",
     "test:watch": "npx jest --watch",
     "coverage": "npx jest --coverage",
@@ -69,7 +70,7 @@
     "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:brand-consistency && 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 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/steering/CORE_PRINCIPLES.md

@@ -128,6 +128,31 @@
 
 **目标**: AI 像人类开发者自由使用开发环境资源，专注解决问题而非权限申请
 
+### 11. 缺陷修复优先根因原则 🛠️
+
+**核心**: 定位问题时，第一要务是修复根因，不是绕过问题
+
+**硬规则**: ❌ 禁止通过关闭校验、跳过测试、降级关键路径、屏蔽异常等方式“假修复”
+
+**复杂问题定位方法**: 优先使用 debug 日志与可观测信号定位（输入、输出、关键分支、异常栈、上下文参数），先还原执行路径再下结论
+
+**允许的临时措施**: 仅在生产止血场景可临时绕行，但必须同时给出根因修复任务、回滚条件和截止时间
+
+**验收标准**: 必须有可复现用例、修复后回归通过、明确根因记录（不是仅现象描述）
+
+### 12. Ontology 四层一链分析原则 🧭
+
+**核心**: 梳理项目必须按统一语义框架推进，避免只看页面或只看接口
+
+**标准口径（修正）**:
+1) 实体模型（Entity）
+2) 关系图谱（Relation）
+3) 业务规则（Business Rule）
+4) 决策逻辑（Decision）
+5) 执行链路（Action/Lineage，体现“决策如何被执行与影响到哪里”）
+
+**要求**: 需求分析、问题定位、模板沉淀、发布门禁均按该口径检查完整性与一致性
+
 ---
 
-v14.0 | 2026-02-02 | 无损重构，精简 40% token
+v15.0 | 2026-02-25 | 新增根因修复原则与 Ontology 四层一链分析原则