scene-capability-engine 3.0.0

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/context-sync-manager.js

@@ -0,0 +1,273 @@
+/**
+ * ContextSyncManager - Maintains CURRENT_CONTEXT.md as multi-Spec progress summary
+ *
+ * Parses and formats CURRENT_CONTEXT.md between Markdown and structured objects.
+ * Uses SteeringFileLock for concurrent write protection in multi-Agent mode.
+ * In single-Agent mode, updateSpecProgress is a no-op.
+ *
+ * Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 6.2
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const fsUtils = require('../utils/fs-utils');
+const { MultiAgentConfig } = require('../collab/multi-agent-config');
+
+const STEERING_DIR = '.kiro/steering';
+const CONTEXT_FILENAME = 'CURRENT_CONTEXT.md';
+const SPECS_DIR = '.kiro/specs';
+
+class ContextSyncManager {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   * @param {import('../lock/steering-file-lock').SteeringFileLock} steeringFileLock
+   */
+  constructor(workspaceRoot, steeringFileLock) {
+    this._workspaceRoot = workspaceRoot;
+    this._steeringFileLock = steeringFileLock;
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+    this._contextPath = path.join(workspaceRoot, STEERING_DIR, CONTEXT_FILENAME);
+  }
+
+  /**
+   * Update the progress entry for a specific Spec.
+   * Uses SteeringFileLock for concurrent write protection.
+   * Single-Agent mode: no-op returning {success: true}.
+   *
+   * @param {string} specName
+   * @param {{status: string, progress: number, summary: string}} entry
+   * @returns {Promise<{success: boolean}>}
+   */
+  async updateSpecProgress(specName, entry) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return { success: true };
+    }
+
+    await this._steeringFileLock.withLock(CONTEXT_FILENAME, async () => {
+      const context = await this.readContext();
+      context.specs[specName] = {
+        status: entry.status,
+        progress: entry.progress,
+        summary: entry.summary,
+      };
+      await this.writeContext(context);
+    });
+
+    return { success: true };
+  }
+
+  /**
+   * Read and parse CURRENT_CONTEXT.md into a structured object.
+   * Returns default empty object if file doesn't exist.
+   *
+   * @returns {Promise<{version: string|null, globalStatus: string|null, specs: object}>}
+   */
+  async readContext() {
+    const exists = await fs.pathExists(this._contextPath);
+    if (!exists) {
+      return { version: null, globalStatus: null, specs: {} };
+    }
+
+    try {
+      const content = await fs.readFile(this._contextPath, 'utf8');
+      return this.parseContext(content);
+    } catch (err) {
+      console.warn(`[ContextSyncManager] Failed to read ${this._contextPath}: ${err.message}`);
+      return { version: null, globalStatus: null, specs: {} };
+    }
+  }
+
+  /**
+   * Write a structured context object back to CURRENT_CONTEXT.md.
+   * Uses atomic write for file integrity.
+   *
+   * @param {{version: string|null, globalStatus: string|null, specs: object}} context
+   * @returns {Promise<void>}
+   */
+  async writeContext(context) {
+    const dir = path.dirname(this._contextPath);
+    await fsUtils.ensureDirectory(dir);
+    const content = this.formatContext(context);
+    await fsUtils.atomicWrite(this._contextPath, content);
+  }
+
+  /**
+   * Compute progress percentage for a Spec based on tasks.md completion.
+   * Counts only leaf tasks (lines matching checkbox patterns).
+   *
+   * @param {string} specName
+   * @returns {Promise<number>} 0-100
+   */
+  async computeProgress(specName) {
+    const tasksPath = path.join(this._workspaceRoot, SPECS_DIR, specName, 'tasks.md');
+    const exists = await fs.pathExists(tasksPath);
+    if (!exists) {
+      return 0;
+    }
+
+    try {
+      const content = await fs.readFile(tasksPath, 'utf8');
+      return this._computeProgressFromContent(content);
+    } catch (err) {
+      console.warn(`[ContextSyncManager] Failed to read ${tasksPath}: ${err.message}`);
+      return 0;
+    }
+  }
+
+  /**
+   * Parse CURRENT_CONTEXT.md Markdown content into a structured object.
+   * Handles both old single-agent format and new multi-agent table format.
+   *
+   * @param {string} content
+   * @returns {{version: string|null, globalStatus: string|null, specs: object}}
+   */
+  parseContext(content) {
+    const result = { version: null, globalStatus: null, specs: {} };
+
+    if (!content || typeof content !== 'string') {
+      return result;
+    }
+
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+
+      // Parse version line: **版本**: ...
+      const versionMatch = trimmed.match(/^\*\*版本\*\*:\s*(.+)$/);
+      if (versionMatch) {
+        result.version = versionMatch[1].trim();
+        continue;
+      }
+
+      // Parse global status line: **状态**: ...
+      const statusMatch = trimmed.match(/^\*\*状态\*\*:\s*(.+)$/);
+      if (statusMatch) {
+        result.globalStatus = statusMatch[1].trim();
+        continue;
+      }
+
+      // Parse table rows for Spec progress
+      // Format: | spec-name | status | progress% | summary |
+      if (trimmed.startsWith('|') && !trimmed.startsWith('|---') && !trimmed.startsWith('| Spec')) {
+        const cells = trimmed.split('|').map(c => c.trim()).filter(c => c.length > 0);
+        if (cells.length >= 4) {
+          const specName = cells[0];
+          const status = cells[1];
+          const progressStr = cells[2].replace('%', '');
+          const progress = parseInt(progressStr, 10);
+          const summary = cells[3];
+
+          if (specName && status && !isNaN(progress)) {
+            result.specs[specName] = { status, progress, summary };
+          }
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Format a structured context object into CURRENT_CONTEXT.md Markdown.
+   *
+   * @param {{version: string|null, globalStatus: string|null, specs: object}} context
+   * @returns {string}
+   */
+  formatContext(context) {
+    const lines = [];
+
+    lines.push('# 当前场景');
+    lines.push('');
+
+    if (context.version) {
+      lines.push(`**版本**: ${context.version}`);
+    }
+    if (context.globalStatus) {
+      lines.push(`**状态**: ${context.globalStatus}`);
+    }
+
+    const specEntries = Object.entries(context.specs || {});
+    if (specEntries.length > 0) {
+      lines.push('');
+      lines.push('## Spec 进度');
+      lines.push('');
+      lines.push('| Spec | 状态 | 进度 | 摘要 |');
+      lines.push('|------|------|------|------|');
+
+      for (const [name, entry] of specEntries) {
+        const status = entry.status || '';
+        const progress = entry.progress != null ? `${entry.progress}%` : '0%';
+        const summary = entry.summary || '';
+        lines.push(`| ${name} | ${status} | ${progress} | ${summary} |`);
+      }
+    }
+
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    const now = new Date();
+    const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+    lines.push(`v1.0 | ${dateStr} | 自动更新`);
+    lines.push('');
+
+    return lines.join('\n');
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Compute progress from tasks.md content.
+   * Counts only leaf tasks (lines with checkbox patterns that have no sub-tasks).
+   *
+   * @param {string} content
+   * @returns {number} 0-100
+   * @private
+   */
+  _computeProgressFromContent(content) {
+    const lines = content.split('\n');
+    // Checkbox pattern: - [ ], - [x], - [-], - [~]
+    const taskPattern = /^(\s*)- \[([ x\-~])\]\*?\s/;
+
+    // First pass: identify all task lines with their indentation levels
+    const tasks = [];
+    for (let i = 0; i < lines.length; i++) {
+      const match = lines[i].match(taskPattern);
+      if (match) {
+        tasks.push({
+          index: i,
+          indent: match[1].length,
+          status: match[2],
+        });
+      }
+    }
+
+    // Second pass: identify leaf tasks (tasks with no sub-tasks)
+    let total = 0;
+    let completed = 0;
+
+    for (let i = 0; i < tasks.length; i++) {
+      const current = tasks[i];
+      const next = tasks[i + 1];
+
+      // A task is a leaf if the next task is not more indented
+      const isLeaf = !next || next.indent <= current.indent;
+
+      if (isLeaf) {
+        total++;
+        if (current.status === 'x') {
+          completed++;
+        }
+      }
+    }
+
+    if (total === 0) {
+      return 0;
+    }
+
+    return Math.round(completed / total * 100);
+  }
+}
+
+module.exports = { ContextSyncManager };

package/lib/steering/index.js

@@ -0,0 +1,92 @@
+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');
+const { SpecSteering } = require('./spec-steering');
+const { SteeringLoader } = require('./steering-loader');
+const { ContextSyncManager } = require('./context-sync-manager');
+
+/**
+ * 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,
+  SpecSteering,
+  SteeringLoader,
+  ContextSyncManager
+};

package/lib/steering/spec-steering.js

@@ -0,0 +1,230 @@
+/**
+ * SpecSteering - Spec 级 steering.md 管理
+ *
+ * 负责 `.kiro/specs/{spec-name}/steering.md` 的 CRUD 操作和模板管理。
+ * 在单 Agent 模式下 createTemplate 为 no-op。
+ *
+ * Requirements: 1.1, 1.3, 1.4, 7.1, 7.2, 7.3
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const fsUtils = require('../utils/fs-utils');
+const { MultiAgentConfig } = require('../collab/multi-agent-config');
+
+const STEERING_FILENAME = 'steering.md';
+const SPECS_DIR = '.kiro/specs';
+
+/**
+ * Section headers used in steering.md template.
+ * Order matters for format output.
+ */
+const SECTIONS = [
+  { key: 'constraints', header: '## 约束 (Constraints)' },
+  { key: 'notes',       header: '## 注意事项 (Notes)' },
+  { key: 'decisions',   header: '## 决策记录 (Decisions)' },
+];
+
+class SpecSteering {
+  /**
+   * @param {string} workspaceRoot - Absolute path to the project root
+   */
+  constructor(workspaceRoot) {
+    this._workspaceRoot = workspaceRoot;
+    this._multiAgentConfig = new MultiAgentConfig(workspaceRoot);
+  }
+
+  /**
+   * Build the absolute path to a Spec's steering.md.
+   * @param {string} specName
+   * @returns {string}
+   */
+  _steeringPath(specName) {
+    return path.join(this._workspaceRoot, SPECS_DIR, specName, STEERING_FILENAME);
+  }
+
+  /**
+   * Generate a steering.md template for the given Spec.
+   * Only executes in multi-Agent mode; single-Agent mode returns no-op.
+   *
+   * @param {string} specName
+   * @returns {Promise<{created: boolean, path: string}>}
+   */
+  async createTemplate(specName) {
+    const enabled = await this._multiAgentConfig.isEnabled();
+    if (!enabled) {
+      return { created: false, path: '' };
+    }
+
+    const filePath = this._steeringPath(specName);
+
+    // Don't overwrite an existing steering.md
+    const exists = await fs.pathExists(filePath);
+    if (exists) {
+      return { created: false, path: filePath };
+    }
+
+    const specDir = path.dirname(filePath);
+    await fsUtils.ensureDirectory(specDir);
+
+    const template = this.format({
+      constraints: [],
+      notes: [],
+      decisions: [],
+    }, specName);
+
+    await fsUtils.atomicWrite(filePath, template);
+    return { created: true, path: filePath };
+  }
+
+  /**
+   * Read and parse a Spec's steering.md into a structured object.
+   * Returns null if the file does not exist.
+   * Returns empty arrays if the file is corrupted / unparseable.
+   *
+   * @param {string} specName
+   * @returns {Promise<{constraints: string[], notes: string[], decisions: string[]}|null>}
+   */
+  async read(specName) {
+    const filePath = this._steeringPath(specName);
+    const exists = await fs.pathExists(filePath);
+    if (!exists) {
+      return null;
+    }
+
+    try {
+      const content = await fs.readFile(filePath, 'utf8');
+      return this.parse(content);
+    } catch (err) {
+      console.warn(`[SpecSteering] Failed to read ${filePath}: ${err.message}`);
+      return { constraints: [], notes: [], decisions: [] };
+    }
+  }
+
+  /**
+   * Write a structured object back to steering.md using atomic write.
+   *
+   * @param {string} specName
+   * @param {{constraints: string[], notes: string[], decisions: string[]}} data
+   * @returns {Promise<void>}
+   */
+  async write(specName, data) {
+    const filePath = this._steeringPath(specName);
+    const specDir = path.dirname(filePath);
+    await fsUtils.ensureDirectory(specDir);
+
+    const content = this.format(data, specName);
+    await fsUtils.atomicWrite(filePath, content);
+  }
+
+  /**
+   * Parse steering.md Markdown content into a structured object.
+   * Gracefully handles corrupted / unexpected content by returning empty arrays.
+   *
+   * @param {string} content - Markdown string
+   * @returns {{constraints: string[], notes: string[], decisions: string[]}}
+   */
+  parse(content) {
+    const result = { constraints: [], notes: [], decisions: [] };
+
+    if (!content || typeof content !== 'string') {
+      return result;
+    }
+
+    try {
+      const lines = content.split('\n');
+      let currentSection = null;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Detect section headers
+        const section = this._detectSection(trimmed);
+        if (section) {
+          currentSection = section;
+          continue;
+        }
+
+        // Collect list items under the current section
+        if (currentSection && trimmed.startsWith('- ')) {
+          const item = trimmed.slice(2).trim();
+          if (item && !item.startsWith('[') ) {
+            // Skip placeholder items like "[约束条目]"
+            result[currentSection].push(item);
+          }
+        }
+      }
+    } catch (err) {
+      console.warn(`[SpecSteering] Failed to parse steering.md content: ${err.message}`);
+      return { constraints: [], notes: [], decisions: [] };
+    }
+
+    return result;
+  }
+
+  /**
+   * Format a structured object into steering.md Markdown.
+   *
+   * @param {{constraints: string[], notes: string[], decisions: string[]}} data
+   * @param {string} [specName=''] - Used for the title line
+   * @returns {string}
+   */
+  format(data, specName = '') {
+    const lines = [];
+
+    // Title
+    lines.push(`# Spec Steering: ${specName}`);
+    lines.push('');
+
+    for (const { key, header } of SECTIONS) {
+      lines.push(header);
+      lines.push('');
+
+      const items = (data && Array.isArray(data[key])) ? data[key] : [];
+      if (items.length === 0) {
+        // Empty section placeholder
+        lines.push(`- [${this._placeholderFor(key)}]`);
+      } else {
+        for (const item of items) {
+          lines.push(`- ${item}`);
+        }
+      }
+
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────
+
+  /**
+   * Detect which section a header line belongs to.
+   * @param {string} trimmedLine
+   * @returns {string|null} Section key or null
+   */
+  _detectSection(trimmedLine) {
+    for (const { key, header } of SECTIONS) {
+      if (trimmedLine === header || trimmedLine.startsWith(header.split(' (')[0])) {
+        return key;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Return the placeholder text for an empty section.
+   * @param {string} sectionKey
+   * @returns {string}
+   */
+  _placeholderFor(sectionKey) {
+    const map = {
+      constraints: '约束条目',
+      notes: '注意事项条目',
+      decisions: '决策条目',
+    };
+    return map[sectionKey] || sectionKey;
+  }
+}
+
+module.exports = { SpecSteering };