scene-capability-engine 3.3.12 → 3.3.14

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.13] - 2026-02-25
+
+### Changed
+- Strengthened steering defect-repair governance with post-fix cleanup hard rule:
+  - After bug fixes are validated, temporary debug logs, ad-hoc probes, one-off scripts, and temporary debug switches must be removed.
+  - Any retained diagnostic logging must be converted to configurable observability controls and default to disabled.
+- Synced the same steering hard rule to both runtime and template steering baselines:
+  - `.sce/steering/CORE_PRINCIPLES.md`
+  - `template/.sce/steering/CORE_PRINCIPLES.md`
+
 ## [3.3.12] - 2026-02-25
 
 ### Changed

package/README.md

@@ -341,7 +341,7 @@ Structure your work with Requirements → Design → Tasks workflow
 ### Multi-Workspace Management 🚀
 - **Workspace Registry**: Manage multiple sce projects from a single location
 - **Quick Switching**: Switch between projects without directory navigation
-- **Data Atomicity**: Single source of truth (`~/.kse/workspace-state.json`)
+- **Data Atomicity**: Single source of truth (`~/.sce/workspace-state.json`)
 - **Cross-Platform**: Consistent path handling across Windows/Linux/macOS
 - **Auto Migration**: Seamless upgrade from legacy workspace format
 
@@ -570,6 +570,12 @@ sce spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # Multi-Spec
 sce context export <spec-name>     # Export context for AI tools
 sce prompt generate <spec> <task>  # Generate task-specific prompt
 
+# Template registry
+sce templates list --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver> --risk <low|medium|high|critical>
+sce templates search <keyword> --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver>
+sce templates show <template-path>  # Show template metadata and compatibility contract
+sce templates update [--source <name>]
+
 # KPI automation and observability
 sce value metrics sample --out <path> --json               # Generate sample KPI input JSON
 sce value metrics snapshot --input <path> --json          # Generate weekly KPI snapshot + gate summary
@@ -769,6 +775,6 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 3.3.1  
-**Last Updated**: 2026-02-22
+**Version**: 3.3.14  
+**Last Updated**: 2026-02-26
 

package/README.zh.md

@@ -307,7 +307,7 @@ sequenceDiagram
 ### 多工作区管理 🚀
 - **工作区注册表**：从单一位置管理多个 sce 项目
 - **快速切换**：无需目录导航即可在项目间切换
-- **数据原子性**：单一数据源（`~/.kse/workspace-state.json`）
+- **数据原子性**：单一数据源（`~/.sce/workspace-state.json`）
 - **跨平台**：Windows/Linux/macOS 一致的路径处理
 - **自动迁移**：从旧版工作区格式无缝升级
 
@@ -484,6 +484,12 @@ sce spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # 多 Spec
 sce context export <spec-name>     # 为 AI 工具导出上下文
 sce prompt generate <spec> <task>  # 生成任务特定提示
 
+# 模板注册表
+sce templates list --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver> --risk <low|medium|high|critical>
+sce templates search <keyword> --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver>
+sce templates show <template-path>  # 查看模板元数据与兼容契约
+sce templates update [--source <name>]
+
 # KPI 自动化与可观测
 sce value metrics sample --out <path> --json               # 生成 KPI 输入样例 JSON
 sce value metrics snapshot --input <path> --json          # 生成周度 KPI 快照 + gate 摘要
@@ -630,7 +636,7 @@ sce spec bootstrap --name 01-00-my-first-feature --non-interactive
 
 ---
 
-**版本**：3.3.1  
-**最后更新**：2026-02-22
+**版本**：3.3.14  
+**最后更新**：2026-02-26
 
 

package/bin/scene-capability-engine.js

@@ -311,7 +311,6 @@ program
         console.log(chalk.yellow('💡 Tip:'));
         console.log('  Use a template: ' + chalk.cyan(`sce spec create ${specName} --template <template-id>`));
         console.log('  Browse templates: ' + chalk.cyan('sce templates list'));
-        console.log('  Legacy alias (still works): ' + chalk.cyan('kse templates list')); 
       }
     } catch (error) {
       console.error(chalk.red('❌ Error creating spec:'), error.message);
@@ -830,13 +829,16 @@ const templatesCommand = require('../lib/commands/templates');
 
 const templatesCmd = program
   .command('templates')
-  .description('Manage Spec templates from official and custom sources');
+  .description('Manage SCE templates from official and custom sources');
 
 templatesCmd
   .command('list')
   .description('List all available templates')
   .option('--category <category>', 'Filter by category')
   .option('--source <source>', 'Filter by source')
+  .option('--type <template-type>', 'Filter by template type (spec-scaffold|capability-template|runtime-playbook)')
+  .option('--compatible-with <version>', 'Filter templates compatible with target SCE version (semver)')
+  .option('--risk <risk-level>', 'Filter by risk level (low|medium|high|critical)')
   .action(async (options) => {
     await templatesCommand.listTemplates(options);
   });
@@ -845,6 +847,10 @@ templatesCmd
   .command('search <keyword>')
   .description('Search templates by keyword')
   .option('--category <category>', 'Filter by category')
+  .option('--source <source>', 'Filter by source')
+  .option('--type <template-type>', 'Filter by template type (spec-scaffold|capability-template|runtime-playbook)')
+  .option('--compatible-with <version>', 'Filter templates compatible with target SCE version (semver)')
+  .option('--risk <risk-level>', 'Filter by risk level (low|medium|high|critical)')
   .action(async (keyword, options) => {
     await templatesCommand.searchTemplates(keyword, options);
   });

package/docs/command-reference.md

@@ -1291,6 +1291,12 @@ Codex sub-agent permission defaults:
 ### Scene Template Engine
 
 ```bash
+# Template registry (typed templates + compatibility filters)
+sce templates list --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver> --risk <low|medium|high|critical>
+sce templates search <keyword> --type <spec-scaffold|capability-template|runtime-playbook> --compatible-with <semver>
+sce templates show <template-path>
+sce templates update [--source <name>]
+
 # Validate template variable schema in a scene package
 sce scene template-validate --package <path>
 sce scene template-validate --package ./my-package --json
@@ -1345,6 +1351,10 @@ sce scene package-publish-batch --manifest docs/handoffs/handoff-manifest.json -
 sce scene package-publish-batch --manifest docs/handoffs/handoff-manifest.json --dry-run --ontology-task-queue-out .sce/auto/ontology-remediation.lines --json
 ```
 
+Compatibility contract note:
+- Scene package compatibility uses `compatibility.min_sce_version` as canonical field.
+- Legacy `compatibility.kse_version` remains readable but is deprecated.
+
 ### Scene Package Ontology Backfill Batch
 
 ```bash

package/lib/commands/scene.js

@@ -3631,9 +3631,23 @@ function buildScenePackageCoordinate(contract = {}) {
   return `${group}/${name}@${version}`;
 }
 
+function resolveSceneCompatibilityMinSceVersion(compatibility = {}) {
+  if (!isPlainObject(compatibility)) {
+    return '';
+  }
+
+  const minSceVersion = String(compatibility.min_sce_version || '').trim();
+  if (minSceVersion.length > 0) {
+    return minSceVersion;
+  }
+
+  return String(compatibility.kse_version || '').trim();
+}
+
 function buildScenePackagePublishTemplateManifest(packageContract = {}, context = {}) {
   const artifacts = isPlainObject(packageContract.artifacts) ? packageContract.artifacts : {};
   const compatibility = isPlainObject(packageContract.compatibility) ? packageContract.compatibility : {};
+  const minSceVersion = resolveSceneCompatibilityMinSceVersion(compatibility);
 
   return {
     apiVersion: SCENE_PACKAGE_TEMPLATE_API_VERSION,
@@ -3646,6 +3660,7 @@ function buildScenePackagePublishTemplateManifest(packageContract = {}, context
       published_at: context.publishedAt || new Date().toISOString()
     },
     compatibility: {
+      min_sce_version: minSceVersion || '>=1.24.0',
       scene_api_version: String(compatibility.scene_api_version || '').trim() || 'sce.scene/v0.2'
     },
     parameters: Array.isArray(packageContract.parameters)
@@ -3680,7 +3695,7 @@ function createScenePackageTemplate(options = {}) {
       summary: `Template contract for ${packageName || 'scene-template'}`
     },
     compatibility: {
-      kse_version: '>=1.24.0',
+      min_sce_version: '>=1.24.0',
       scene_api_version: 'sce.scene/v0.2',
       moqui_model_version: '3.x',
       adapter_api_version: 'v1'
@@ -4215,9 +4230,21 @@ function validateScenePackageContract(contract = {}) {
   if (!compatibility) {
     errors.push('compatibility object is required');
   } else {
-    if (!String(compatibility.kse_version || '').trim()) {
-      errors.push('compatibility.kse_version is required');
+    const minSceVersion = String(compatibility.min_sce_version || '').trim();
+    const legacyKseVersion = String(compatibility.kse_version || '').trim();
+
+    if (!minSceVersion && !legacyKseVersion) {
+      errors.push('compatibility.min_sce_version is required');
+    }
+
+    if (!minSceVersion && legacyKseVersion) {
+      warnings.push('compatibility.kse_version is deprecated; use compatibility.min_sce_version');
     }
+
+    if (minSceVersion && legacyKseVersion && minSceVersion !== legacyKseVersion) {
+      warnings.push('compatibility.min_sce_version takes precedence over compatibility.kse_version when both are defined');
+    }
+
     if (!String(compatibility.scene_api_version || '').trim()) {
       errors.push('compatibility.scene_api_version is required');
     }

package/lib/commands/templates.js

@@ -1,7 +1,7 @@
 /**
  * Templates Command
  * 
- * Manages Spec templates from official and custom sources
+ * Manages SCE templates from official and custom sources
  */
 
 const chalk = require('chalk');
@@ -18,12 +18,12 @@ const { TemplateError } = require('../templates/template-error');
  * @returns {void}
  */
 function displayTemplateList(templates, options = {}) {
-  const { source = null, category = null } = options;
+  const { source = null, category = null, type = null, compatibleWith = null } = options;
   
   if (templates.length === 0) {
     console.log(chalk.yellow('No templates found'));
     
-    if (source || category) {
+    if (source || category || type || compatibleWith) {
       console.log(chalk.gray('Try removing filters or updating templates'));
     } else {
       console.log(chalk.gray('Run'), chalk.cyan('sce templates update'), chalk.gray('to download templates'));
@@ -62,7 +62,10 @@ function displayTemplateList(templates, options = {}) {
       console.log(`  ${sourcePrefix}${chalk.cyan(template.id)}`);
       console.log(`    ${template.name}`);
       console.log(`    ${chalk.gray(template.description)}`);
+      const templateType = template.template_type || 'spec-scaffold';
+      const compatibility = formatCompatibilityRange(template);
       console.log(`    ${difficultyColor(template.difficulty)} • ${chalk.gray(template.tags.join(', '))}`);
+      console.log(`    ${chalk.gray(`type=${templateType} compatibility=${compatibility}`)}`);
       console.log();
     });
   });
@@ -91,6 +94,12 @@ function displayTemplateDetails(template) {
   }[template.difficulty] || chalk.gray;
   
   console.log(chalk.gray('Difficulty:'), difficultyColor(template.difficulty));
+  console.log(chalk.gray('Type:'), template.template_type || 'spec-scaffold');
+  console.log(chalk.gray('Compatibility:'), formatCompatibilityRange(template));
+
+  if (template.risk_level) {
+    console.log(chalk.gray('Risk Level:'), template.risk_level);
+  }
   
   if (template.source) {
     console.log(chalk.gray('Source:'), template.source);
@@ -121,6 +130,24 @@ function displayTemplateDetails(template) {
     });
     console.log();
   }
+
+  if (template.ontology_scope) {
+    console.log(chalk.gray('Ontology Scope:'));
+    const scopeKeys = ['domains', 'entities', 'relations', 'business_rules', 'decisions'];
+    scopeKeys.forEach((key) => {
+      const values = template.ontology_scope[key];
+      if (Array.isArray(values) && values.length > 0) {
+        console.log(`  • ${key}: ${values.join(', ')}`);
+      }
+    });
+    console.log();
+  }
+
+  if (template.rollback_contract) {
+    const strategy = template.rollback_contract.strategy || 'n/a';
+    console.log(chalk.gray('Rollback Contract:'), `${template.rollback_contract.supported ? 'supported' : 'not-supported'} (strategy=${strategy})`);
+    console.log();
+  }
   
   if (template.author) {
     console.log(chalk.gray('Author:'), template.author);
@@ -136,7 +163,11 @@ function displayTemplateDetails(template) {
   
   console.log();
   console.log(chalk.blue('Usage:'));
-  console.log(`  ${chalk.cyan(`sce spec create my-feature --template ${template.id}`)}`);
+  if ((template.template_type || 'spec-scaffold') === 'spec-scaffold') {
+    console.log(`  ${chalk.cyan(`sce spec create my-feature --template ${template.id}`)}`);
+  } else {
+    console.log(`  ${chalk.cyan(`sce templates show ${template.id}`)} ${chalk.gray('# inspect contract and owning workflow')}`);
+  }
   console.log();
 }
 
@@ -147,15 +178,32 @@ function displayTemplateDetails(template) {
  * @returns {Promise<void>}
  */
 async function listTemplates(options = {}) {
-  const { category = null, source = null } = options;
+  const {
+    category = null,
+    source = null,
+    type = null,
+    compatibleWith = null,
+    risk = null
+  } = options;
   
-  console.log(chalk.red('🔥') + ' Spec Templates');
+  console.log(chalk.red('🔥') + ' SCE Templates');
   
   try {
     const manager = new TemplateManager();
-    const templates = await manager.listTemplates({ category, source });
+    const templates = await manager.listTemplates({
+      category,
+      source,
+      templateType: type,
+      compatibleWith,
+      riskLevel: risk
+    });
     
-    displayTemplateList(templates, { category, source });
+    displayTemplateList(templates, {
+      category,
+      source,
+      type,
+      compatibleWith
+    });
     
   } catch (error) {
     console.log();
@@ -183,15 +231,32 @@ async function listTemplates(options = {}) {
  * @returns {Promise<void>}
  */
 async function searchTemplates(keyword, options = {}) {
-  const { category = null } = options;
+  const {
+    category = null,
+    source = null,
+    type = null,
+    compatibleWith = null,
+    risk = null
+  } = options;
   
   console.log(chalk.red('🔥') + ` Searching templates for: ${chalk.cyan(keyword)}`);
   
   try {
     const manager = new TemplateManager();
-    const templates = await manager.searchTemplates(keyword, { category });
+    const templates = await manager.searchTemplates(keyword, {
+      source,
+      category,
+      templateType: type,
+      compatibleWith,
+      riskLevel: risk
+    });
     
-    displayTemplateList(templates, { category });
+    displayTemplateList(templates, {
+      category,
+      source,
+      type,
+      compatibleWith
+    });
     
   } catch (error) {
     console.log();
@@ -525,6 +590,18 @@ async function cacheCommand(options = {}) {
   }
 }
 
+/**
+ * Format compatibility range for display
+ *
+ * @param {Object} template - Template metadata
+ * @returns {string} Compatibility text
+ */
+function formatCompatibilityRange(template) {
+  const min = template.min_sce_version || '*';
+  const max = template.max_sce_version || '*';
+  return `${min}..${max}`;
+}
+
 /**
  * Format bytes to human-readable string
  * 
@@ -547,21 +624,20 @@ function formatBytes(bytes) {
  * @returns {Promise<void>}
  */
 async function displayGuide() {
-  console.log(chalk.red('🔥') + ' Spec Template Guide');
+  console.log(chalk.red('🔥') + ' SCE Template Guide');
   console.log();
   
-  console.log(chalk.blue.bold('What are Spec Templates?'));
+  console.log(chalk.blue.bold('What are SCE Templates?'));
   console.log();
-  console.log('Spec templates are pre-built frameworks for common feature types.');
-  console.log('They provide structured requirements, design patterns, and task lists');
-  console.log('to help you get started quickly with best practices.');
+  console.log('SCE templates include spec scaffolds, capability templates, and runtime playbooks.');
+  console.log('They provide reusable contracts for generation, execution, and verification workflows.');
   console.log();
   
   console.log(chalk.blue.bold('Quick Start:'));
   console.log();
   console.log(`1. ${chalk.cyan('sce templates list')} - Browse available templates`);
   console.log(`2. ${chalk.cyan('sce templates show <template-id>')} - View template details`);
-  console.log(`3. ${chalk.cyan('sce spec create my-feature --template <template-id>')} - Create spec from template`);
+  console.log(`3. ${chalk.cyan('sce spec create my-feature --template <template-id>')} - Apply scaffold template`);
   console.log();
   
   console.log(chalk.blue.bold('Common Commands:'));

package/lib/scene-runtime/moqui-extractor.js

@@ -1643,7 +1643,7 @@ function generatePackageContract(match) {
       description: `${summary}. Includes ontology graph hints, lineage tracing, and AI execution metadata.`
     },
     compatibility: {
-      kse_version: '>=1.39.0',
+      min_sce_version: '>=1.39.0',
       scene_api_version: SCENE_API_VERSION
     },
     parameters: [

package/lib/templates/cache-manager.js

@@ -11,8 +11,8 @@ const { FileSystemError } = require('./template-error');
 
 class CacheManager {
   constructor(cacheDir = null) {
-    // Default cache directory: ~/.kse/templates/
-    this.cacheDir = cacheDir || path.join(os.homedir(), '.kse', 'templates');
+    // Default cache directory: ~/.sce/templates/
+    this.cacheDir = cacheDir || path.join(os.homedir(), '.sce', 'templates');
     this.metadataFile = path.join(this.cacheDir, '.cache-metadata.json');
     this.sourcesFile = path.join(this.cacheDir, '.sources.json');
   }
@@ -215,7 +215,7 @@ class CacheManager {
     } else {
       // Get info for all sources
       const metadata = await this.getMetadata();
-      const totalSize = await getTotalCacheSize();
+      const totalSize = await this.getTotalCacheSize();
 
       return {
         cacheDir: this.cacheDir,

package/lib/templates/frontmatter-generator.js

@@ -22,7 +22,8 @@ class FrontmatterGenerator {
       created_at: metadata.created_at,
       updated_at: metadata.updated_at,
       version: metadata.version,
-      kse_version: metadata.kse_version
+      template_type: metadata.template_type,
+      min_sce_version: metadata.min_sce_version
     };
 
     // Add optional fields if present
@@ -32,6 +33,15 @@ class FrontmatterGenerator {
     if (metadata.applicable_scenarios) {
       frontmatterData.applicable_scenarios = metadata.applicable_scenarios;
     }
+    if (metadata.max_sce_version) {
+      frontmatterData.max_sce_version = metadata.max_sce_version;
+    }
+    if (metadata.risk_level) {
+      frontmatterData.risk_level = metadata.risk_level;
+    }
+    if (metadata.rollback_contract) {
+      frontmatterData.rollback_contract = metadata.rollback_contract;
+    }
 
     try {
       const yamlContent = yaml.dump(frontmatterData, {

package/lib/templates/metadata-collector.js

@@ -4,6 +4,7 @@
 
 const inquirer = require('inquirer');
 const { execSync } = require('child_process');
+const semver = require('semver');
 
 class MetadataCollector {
   constructor(options = {}) {
@@ -50,8 +51,19 @@ class MetadataCollector {
     // Version
     metadata.version = await this.promptVersion();
 
-    // sce version
-    metadata.kse_version = await this.promptKseVersion();
+    // Template type and compatibility
+    metadata.template_type = 'spec-scaffold';
+    metadata.min_sce_version = await this.promptMinSceVersion();
+    metadata.max_sce_version = null;
+
+    // Default typed metadata for scaffold templates
+    metadata.difficulty = 'intermediate';
+    metadata.applicable_scenarios = [];
+    metadata.risk_level = 'medium';
+    metadata.rollback_contract = {
+      supported: true,
+      strategy: 'git-revert'
+    };
 
     // Timestamps
     const now = new Date().toISOString().split('T')[0];
@@ -214,17 +226,17 @@ class MetadataCollector {
    * Prompts for sce version
    * @returns {Promise<string>} sce version
    */
-  async promptKseVersion() {
-    const currentVersion = this.getCurrentKseVersion();
-    const { kseVersion } = await inquirer.prompt([
+  async promptMinSceVersion() {
+    const currentVersion = this.getCurrentSceVersion();
+    const { minSceVersion } = await inquirer.prompt([
       {
         type: 'input',
-        name: 'kseVersion',
+        name: 'minSceVersion',
         message: 'Minimum sce version required:',
         default: currentVersion
       }
     ]);
-    return kseVersion;
+    return minSceVersion;
   }
 
   /**
@@ -234,7 +246,7 @@ class MetadataCollector {
    */
   validateMetadata(metadata) {
     const errors = [];
-    const requiredFields = ['name', 'description', 'category', 'tags', 'author', 'version', 'kse_version'];
+    const requiredFields = ['name', 'description', 'category', 'tags', 'author', 'version', 'template_type', 'min_sce_version'];
 
     for (const field of requiredFields) {
       if (!metadata[field]) {
@@ -252,11 +264,28 @@ class MetadataCollector {
       errors.push('Version must follow semver format');
     }
 
+    if (metadata.min_sce_version && !semver.valid(metadata.min_sce_version)) {
+      errors.push('min_sce_version must be a valid semver version');
+    }
+
+    if (metadata.max_sce_version) {
+      if (!semver.valid(metadata.max_sce_version)) {
+        errors.push('max_sce_version must be a valid semver version');
+      } else if (metadata.min_sce_version && semver.gt(metadata.min_sce_version, metadata.max_sce_version)) {
+        errors.push('min_sce_version must be less than or equal to max_sce_version');
+      }
+    }
+
     // Validate category
     if (metadata.category && !this.categories.includes(metadata.category)) {
       errors.push(`Category must be one of: ${this.categories.join(', ')}`);
     }
 
+    const validTemplateTypes = ['spec-scaffold', 'capability-template', 'runtime-playbook'];
+    if (metadata.template_type && !validTemplateTypes.includes(metadata.template_type)) {
+      errors.push(`template_type must be one of: ${validTemplateTypes.join(', ')}`);
+    }
+
     return {
       valid: errors.length === 0,
       errors
@@ -293,7 +322,16 @@ class MetadataCollector {
       tags: [],
       author: specMetadata.author || this.getGitUser(),
       version: '1.0.0',
-      kse_version: this.getCurrentKseVersion(),
+      template_type: 'spec-scaffold',
+      min_sce_version: this.getCurrentSceVersion(),
+      max_sce_version: null,
+      difficulty: 'intermediate',
+      applicable_scenarios: [],
+      risk_level: 'medium',
+      rollback_contract: {
+        supported: true,
+        strategy: 'git-revert'
+      },
       created_at: now,
       updated_at: now
     };
@@ -315,7 +353,7 @@ class MetadataCollector {
    * Gets current sce version
    * @returns {string} sce version
    */
-  getCurrentKseVersion() {
+  getCurrentSceVersion() {
     try {
       const packageJson = require('../../package.json');
       return packageJson.version;

package/lib/templates/path-utils.js

@@ -51,7 +51,7 @@ function expandHome(filePath) {
  * @returns {string} Path to cache directory
  */
 function getDefaultCacheDir() {
-  return normalize(path.join(os.homedir(), '.kse', 'templates'));
+  return normalize(path.join(os.homedir(), '.sce', 'templates'));
 }
 
 /**