kiro-spec-engine 1.12.2 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Steering Directory Compliance Check with Auto-Fix**: Automatic validation and repair of `.kiro/steering/` directory
+  - Enforces allowlist of 4 files: CORE_PRINCIPLES.md, ENVIRONMENT.md, CURRENT_CONTEXT.md, RULES_GUIDE.md
+  - Prohibits subdirectories to prevent context pollution
+  - **Auto-fix feature**: Automatically backs up and removes violations without user confirmation
+  - **Multi-user support**: Detects and respects `contexts/` multi-user collaboration setup
+  - Differential backup: Only backs up violating files/directories (not entire .kiro/)
+  - Backup location: `.kiro/backups/steering-cleanup-{timestamp}/`
+  - Version-based caching (~/.kse/steering-check-cache.json) to avoid repeated checks
+  - Performance target: <50ms per check
+  - Clear progress messages during auto-fix
+  - Bypass options: `--skip-steering-check` flag and `KSE_SKIP_STEERING_CHECK` environment variable
+  - Force check option: `--force-steering-check` flag
+  - Comprehensive documentation in `.kiro/README.md`
+
+### Changed
+- **CLI**: All commands now run steering directory compliance check before execution
+- **Auto-fix behavior**: Violations are automatically fixed (backup + clean) without user confirmation
+- **Multi-user awareness**: Auto-fix shows informational message when multi-user project detected
+- **Documentation**: Added "Steering Directory Compliance" section with multi-user guidance to `.kiro/README.md`
+
+### Breaking Changes
+- Commands will automatically fix steering directory violations on first run
+- Violating files/directories are backed up to `.kiro/backups/steering-cleanup-{timestamp}/`
+- Use `--skip-steering-check` flag to bypass if needed during migration
+- Multi-user projects: Personal contexts in `contexts/` are preserved during auto-fix
+
+## [1.12.3] - 2026-01-29
+
+### Added
+- **Documentation Enhancement**: Comprehensive `.kiro/README.md` update (v2.0)
+  - Added complete directory structure documentation with purpose explanations
+  - Added workspace management section with detailed usage examples
+  - Added document governance section with validation commands
+  - Added data storage location details for `kse workspace` feature
+  - Added JSON data structure examples for workspace-state.json
+  - Clarified difference between `kse workspace` (cross-project) and `contexts/` (multi-user)
+  - Added key features list for workspace management
+
+### Changed
+- **Documentation**: Updated `.kiro/README.md` version to 2.0 with comprehensive feature documentation
+- **Documentation**: Enhanced workspace storage explanation with platform-specific paths
+
 ## [1.12.2] - 2026-01-29
 
 ### Added

package/bin/kiro-spec-engine.js

@@ -44,7 +44,9 @@ program
   .option('-l, --lang <locale>', 'Set language (en/zh)', (locale) => {
     i18n.setLocale(locale);
   })
-  .option('--no-version-check', 'Suppress version mismatch warnings');
+  .option('--no-version-check', 'Suppress version mismatch warnings')
+  .option('--skip-steering-check', 'Skip steering directory compliance check (not recommended)')
+  .option('--force-steering-check', 'Force steering directory compliance check even if cache is valid');
 
 // 初始化项目命令
 program
@@ -478,5 +480,24 @@ async function updateProjectConfig(projectName) {
   }
 }
 
-// 解析命令行参数
-program.parse();
+// Run steering directory compliance check before parsing commands
+(async function() {
+  const { runSteeringComplianceCheck } = require('../lib/steering');
+  
+  // Check for bypass flags
+  const args = process.argv.slice(2);
+  const skipCheck = args.includes('--skip-steering-check') || 
+                    process.env.KSE_SKIP_STEERING_CHECK === '1';
+  const forceCheck = args.includes('--force-steering-check');
+  
+  // Run compliance check
+  await runSteeringComplianceCheck({
+    skip: skipCheck,
+    force: forceCheck,
+    projectPath: process.cwd(),
+    version: packageJson.version
+  });
+
+  // 解析命令行参数
+  program.parse();
+})();

package/lib/steering/compliance-auto-fixer.js

@@ -0,0 +1,204 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Automatically fix steering directory compliance violations
+ * by backing up and removing disallowed files and subdirectories
+ */
+class ComplianceAutoFixer {
+  /**
+   * Fix compliance violations automatically (no user confirmation)
+   * @param {string} steeringPath - Path to steering directory
+   * @param {Array} violations - List of violations from compliance check
+   * @returns {Object} Fix result with backup info and cleaned files
+   */
+  async fix(steeringPath, violations) {
+    if (!violations || violations.length === 0) {
+      return {
+        success: true,
+        message: 'No violations to fix',
+        backupPath: null,
+        cleanedFiles: [],
+        cleanedDirs: []
+      };
+    }
+
+    // Separate violations by type
+    const disallowedFiles = violations
+      .filter(v => v.type === 'disallowed_file')
+      .map(v => v.name);
+    const subdirectories = violations
+      .filter(v => v.type === 'subdirectory')
+      .map(v => v.name);
+
+    // Check if this is a multi-user project (contexts/ directory exists)
+    const contextsPath = path.join(path.dirname(path.dirname(steeringPath)), 'contexts');
+    const isMultiUser = await fs.pathExists(contextsPath);
+
+    // Show what will be fixed
+    console.log(chalk.yellow('\n🔧 Auto-fixing steering directory compliance violations...\n'));
+    
+    if (disallowedFiles.length > 0) {
+      console.log(chalk.yellow('Disallowed files to be removed:'));
+      disallowedFiles.forEach(file => console.log(`  - ${file}`));
+      console.log();
+    }
+    
+    if (subdirectories.length > 0) {
+      console.log(chalk.yellow('Subdirectories to be removed:'));
+      subdirectories.forEach(dir => console.log(`  - ${dir}/`));
+      console.log();
+    }
+
+    // Show multi-user warning if applicable
+    if (isMultiUser) {
+      console.log(chalk.blue('ℹ️  Multi-user project detected'));
+      console.log(chalk.blue('   Your personal CURRENT_CONTEXT.md is preserved in contexts/'));
+      console.log();
+    }
+
+    // Create backup
+    const backupPath = await this._createBackup(steeringPath, disallowedFiles, subdirectories);
+    console.log(chalk.green(`✓ Backup created: ${backupPath}\n`));
+
+    // Clean up violations
+    const cleanedFiles = [];
+    const cleanedDirs = [];
+
+    // Remove disallowed files
+    for (const file of disallowedFiles) {
+      const filePath = path.join(steeringPath, file);
+      try {
+        await fs.remove(filePath);
+        cleanedFiles.push(file);
+        console.log(chalk.green(`✓ Removed file: ${file}`));
+      } catch (error) {
+        console.error(chalk.red(`✗ Failed to remove ${file}: ${error.message}`));
+      }
+    }
+
+    // Remove subdirectories
+    for (const dir of subdirectories) {
+      const dirPath = path.join(steeringPath, dir);
+      try {
+        await fs.remove(dirPath);
+        cleanedDirs.push(dir);
+        console.log(chalk.green(`✓ Removed directory: ${dir}/`));
+      } catch (error) {
+        console.error(chalk.red(`✗ Failed to remove ${dir}/: ${error.message}`));
+      }
+    }
+
+    console.log(chalk.green('\n✓ Steering directory cleaned successfully!\n'));
+    console.log(chalk.blue('Backup location:'));
+    console.log(`  ${backupPath}\n`);
+    console.log(chalk.blue('To restore from backup:'));
+    console.log(`  kse rollback --backup ${path.basename(backupPath)}\n`);
+
+    return {
+      success: true,
+      message: 'Steering directory fixed successfully',
+      backupPath,
+      cleanedFiles,
+      cleanedDirs
+    };
+  }
+
+  /**
+   * Create differential backup of violations only
+   * @private
+   */
+  async _createBackup(steeringPath, files, dirs) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+    const backupId = `steering-cleanup-${timestamp}`;
+    const backupPath = path.join(path.dirname(path.dirname(steeringPath)), 'backups', backupId);
+
+    // Create backup directory
+    await fs.ensureDir(backupPath);
+
+    // Backup disallowed files
+    for (const file of files) {
+      const sourcePath = path.join(steeringPath, file);
+      const destPath = path.join(backupPath, file);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+      }
+    }
+
+    // Backup subdirectories
+    for (const dir of dirs) {
+      const sourcePath = path.join(steeringPath, dir);
+      const destPath = path.join(backupPath, dir);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+      }
+    }
+
+    // Create backup manifest
+    const manifest = {
+      backupId,
+      timestamp: new Date().toISOString(),
+      type: 'steering-cleanup',
+      steeringPath,
+      files,
+      directories: dirs,
+      totalItems: files.length + dirs.length
+    };
+
+    await fs.writeJson(path.join(backupPath, 'manifest.json'), manifest, { spaces: 2 });
+
+    return backupPath;
+  }
+
+  /**
+   * Restore from backup
+   * @param {string} backupPath - Path to backup directory
+   * @param {string} steeringPath - Path to steering directory
+   */
+  async restore(backupPath, steeringPath) {
+    // Read manifest
+    const manifestPath = path.join(backupPath, 'manifest.json');
+    if (!await fs.pathExists(manifestPath)) {
+      throw new Error('Invalid backup: manifest.json not found');
+    }
+
+    const manifest = await fs.readJson(manifestPath);
+
+    console.log(chalk.yellow('\n🔄 Restoring from backup...\n'));
+
+    // Restore files
+    for (const file of manifest.files) {
+      const sourcePath = path.join(backupPath, file);
+      const destPath = path.join(steeringPath, file);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        console.log(chalk.green(`✓ Restored file: ${file}`));
+      }
+    }
+
+    // Restore directories
+    for (const dir of manifest.directories) {
+      const sourcePath = path.join(backupPath, dir);
+      const destPath = path.join(steeringPath, dir);
+      
+      if (await fs.pathExists(sourcePath)) {
+        await fs.copy(sourcePath, destPath);
+        console.log(chalk.green(`✓ Restored directory: ${dir}/`));
+      }
+    }
+
+    console.log(chalk.green('\n✓ Restore completed!\n'));
+
+    return {
+      success: true,
+      restoredFiles: manifest.files,
+      restoredDirs: manifest.directories
+    };
+  }
+}
+
+module.exports = ComplianceAutoFixer;

package/lib/steering/compliance-cache.js

@@ -0,0 +1,99 @@
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+
+/**
+ * ComplianceCache - Manages version-based check caching
+ * 
+ * Stores the last successful compliance check version to avoid
+ * repeated checks for the same kse version.
+ */
+class ComplianceCache {
+  /**
+   * Create a new ComplianceCache instance
+   * 
+   * @param {string} cachePath - Optional custom cache file path
+   */
+  constructor(cachePath = null) {
+    this.cachePath = cachePath || this.getDefaultCachePath();
+  }
+
+  /**
+   * Get the default cache file path
+   * 
+   * @returns {string} Path to ~/.kse/steering-check-cache.json
+   */
+  getDefaultCachePath() {
+    const homeDir = os.homedir();
+    return path.join(homeDir, '.kse', 'steering-check-cache.json');
+  }
+
+  /**
+   * Check if cache is valid for current version
+   * 
+   * @param {string} currentVersion - Current kse version
+   * @returns {boolean} True if cache is valid
+   */
+  isValid(currentVersion) {
+    try {
+      if (!fs.existsSync(this.cachePath)) {
+        return false;
+      }
+
+      const cache = JSON.parse(fs.readFileSync(this.cachePath, 'utf8'));
+      return cache.version === currentVersion && cache.lastCheck === 'success';
+    } catch (error) {
+      // Treat any cache read error as cache miss
+      return false;
+    }
+  }
+
+  /**
+   * Update cache with successful check
+   * 
+   * @param {string} version - kse version
+   * @returns {boolean} True if update succeeded
+   */
+  update(version) {
+    try {
+      const cacheDir = path.dirname(this.cachePath);
+      
+      // Ensure cache directory exists
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+
+      const cacheData = {
+        version,
+        timestamp: new Date().toISOString(),
+        lastCheck: 'success'
+      };
+
+      fs.writeFileSync(this.cachePath, JSON.stringify(cacheData, null, 2), 'utf8');
+      return true;
+    } catch (error) {
+      // Log error but don't throw - cache write failure is not critical
+      console.warn(`Warning: Failed to update compliance cache: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Clear the cache
+   * 
+   * @returns {boolean} True if clear succeeded
+   */
+  clear() {
+    try {
+      if (fs.existsSync(this.cachePath)) {
+        fs.unlinkSync(this.cachePath);
+      }
+      return true;
+    } catch (error) {
+      console.warn(`Warning: Failed to clear compliance cache: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+module.exports = ComplianceCache;

package/lib/steering/compliance-error-reporter.js

@@ -0,0 +1,70 @@
+const chalk = require('chalk');
+
+/**
+ * ComplianceErrorReporter - Formats and displays compliance violations
+ * 
+ * Creates user-friendly error messages with clear sections,
+ * violation details, and actionable fix suggestions.
+ */
+class ComplianceErrorReporter {
+  /**
+   * Format compliance violations into user-friendly message
+   * 
+   * @param {ComplianceViolation[]} violations - List of violations
+   * @returns {string} Formatted error message
+   */
+  formatError(violations) {
+    const disallowedFiles = violations.filter(v => v.type === 'disallowed_file');
+    const subdirectories = violations.filter(v => v.type === 'subdirectory');
+
+    let message = '\n';
+    message += chalk.red.bold('❌ Steering Directory Compliance Check Failed') + '\n\n';
+    message += 'The .kiro/steering/ directory contains files or subdirectories that are not allowed.\n';
+    message += 'This directory is automatically loaded in every AI session, so keeping it clean is critical.\n\n';
+
+    message += chalk.yellow.bold('Violations Found:') + '\n';
+    
+    if (disallowedFiles.length > 0) {
+      message += '  • ' + chalk.yellow('Disallowed files:') + '\n';
+      disallowedFiles.forEach(v => {
+        message += `    - ${v.name}\n`;
+      });
+    }
+    
+    if (subdirectories.length > 0) {
+      message += '  • ' + chalk.yellow('Subdirectories (not allowed):') + '\n';
+      subdirectories.forEach(v => {
+        message += `    - ${v.name}/\n`;
+      });
+    }
+
+    message += '\n' + chalk.green.bold('Allowed Files:') + '\n';
+    message += '  ✓ CORE_PRINCIPLES.md\n';
+    message += '  ✓ ENVIRONMENT.md\n';
+    message += '  ✓ CURRENT_CONTEXT.md\n';
+    message += '  ✓ RULES_GUIDE.md\n';
+
+    message += '\n' + chalk.cyan.bold('Fix Suggestions:') + '\n';
+    message += '  • Move analysis reports to: .kiro/specs/{spec-name}/reports/\n';
+    message += '  • Move historical data to: .kiro/specs/{spec-name}/\n';
+    message += '  • Move detailed docs to: docs/\n';
+    message += '  • Delete temporary files\n';
+
+    message += '\n' + chalk.gray('To bypass this check (not recommended):') + '\n';
+    message += chalk.gray('  kse <command> --skip-steering-check') + '\n';
+
+    return message;
+  }
+
+  /**
+   * Display error and exit
+   * 
+   * @param {ComplianceViolation[]} violations - List of violations
+   */
+  reportAndExit(violations) {
+    console.error(this.formatError(violations));
+    process.exit(1);
+  }
+}
+
+module.exports = ComplianceErrorReporter;

package/lib/steering/index.js

@@ -0,0 +1,86 @@
+const path = require('path');
+const SteeringComplianceChecker = require('./steering-compliance-checker');
+const ComplianceCache = require('./compliance-cache');
+const ComplianceErrorReporter = require('./compliance-error-reporter');
+const ComplianceAutoFixer = require('./compliance-auto-fixer');
+
+/**
+ * Run steering directory compliance check
+ * 
+ * @param {Object} options - Check options
+ * @param {boolean} options.skip - Skip the check entirely
+ * @param {boolean} options.force - Force check even if cache is valid
+ * @param {string} options.projectPath - Project root path (defaults to cwd)
+ * @param {string} options.version - Current kse version
+ * @returns {boolean} True if compliant or check skipped, false otherwise
+ */
+async function runSteeringComplianceCheck(options = {}) {
+  const {
+    skip = false,
+    force = false,
+    projectPath = process.cwd(),
+    version = require('../../package.json').version
+  } = options;
+
+  // Skip check if requested
+  if (skip) {
+    return true;
+  }
+
+  try {
+    const checker = new SteeringComplianceChecker();
+    const cache = new ComplianceCache();
+    const reporter = new ComplianceErrorReporter();
+    const fixer = new ComplianceAutoFixer();
+
+    // Check cache unless forced
+    if (!force && cache.isValid(version)) {
+      // Cache is valid, skip check
+      return true;
+    }
+
+    // Perform compliance check with performance measurement
+    const startTime = Date.now();
+    const steeringPath = path.join(projectPath, '.kiro', 'steering');
+    const result = checker.check(steeringPath);
+    const duration = Date.now() - startTime;
+
+    // Log warning if check exceeds performance target
+    if (duration > 50) {
+      console.warn(`Warning: Steering compliance check took ${duration}ms (target: <50ms)`);
+    }
+
+    if (!result.compliant) {
+      // Auto-fix violations
+      console.log(''); // Empty line for better formatting
+      const fixResult = await fixer.fix(steeringPath, result.violations);
+      
+      if (fixResult.success) {
+        console.log('✓ Steering directory is now compliant\n');
+        // Update cache after successful fix
+        cache.update(version);
+        return true;
+      } else {
+        // If fix failed, report and exit
+        reporter.reportAndExit(result.violations);
+        return false;
+      }
+    }
+
+    // Update cache on success
+    cache.update(version);
+    return true;
+  } catch (error) {
+    // Log error but don't block execution
+    console.warn(`Warning: Steering compliance check failed: ${error.message}`);
+    return true; // Allow execution to proceed
+  }
+}
+
+module.exports = {
+  runSteeringComplianceCheck,
+  SteeringComplianceChecker,
+  ComplianceCache,
+  ComplianceErrorReporter,
+  ComplianceAutoFixer
+};

package/lib/steering/steering-compliance-checker.js

@@ -0,0 +1,73 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * SteeringComplianceChecker - Validates steering directory compliance
+ * 
+ * Ensures the .kiro/steering/ directory contains only allowed files
+ * and no subdirectories to prevent context pollution and excessive
+ * token consumption in AI sessions.
+ */
+class SteeringComplianceChecker {
+  /**
+   * Get list of allowed files in steering directory
+   * 
+   * @returns {string[]} Array of allowed file names
+   */
+  getAllowedFiles() {
+    return [
+      'CORE_PRINCIPLES.md',
+      'ENVIRONMENT.md',
+      'CURRENT_CONTEXT.md',
+      'RULES_GUIDE.md'
+    ];
+  }
+
+  /**
+   * Check if steering directory is compliant
+   * 
+   * @param {string} steeringPath - Path to steering directory
+   * @returns {ComplianceResult} Result with status and violations
+   */
+  check(steeringPath) {
+    // Non-existent directory is compliant
+    if (!fs.existsSync(steeringPath)) {
+      return { compliant: true };
+    }
+
+    const violations = [];
+    const allowedFiles = this.getAllowedFiles();
+    
+    try {
+      const entries = fs.readdirSync(steeringPath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          // Subdirectories are not allowed
+          violations.push({
+            type: 'subdirectory',
+            name: entry.name,
+            path: path.join(steeringPath, entry.name)
+          });
+        } else if (!allowedFiles.includes(entry.name)) {
+          // File not in allowlist
+          violations.push({
+            type: 'disallowed_file',
+            name: entry.name,
+            path: path.join(steeringPath, entry.name)
+          });
+        }
+      }
+      
+      return {
+        compliant: violations.length === 0,
+        violations
+      };
+    } catch (error) {
+      // Re-throw unexpected errors
+      throw error;
+    }
+  }
+}
+
+module.exports = SteeringComplianceChecker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {