kiro-spec-engine 1.45.13 → 1.46.0

package/lib/spec/multi-spec-orchestrate.js

@@ -0,0 +1,93 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Parse --spec / --specs options into a de-duplicated list.
+ *
+ * @param {object} options
+ * @returns {string[]}
+ */
+function parseSpecTargets(options = {}) {
+  const fromSpec = (options.spec || '').trim();
+  const fromSpecs = `${options.specs || ''}`
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+
+  const merged = [];
+  if (fromSpec) {
+    merged.push(fromSpec);
+  }
+  merged.push(...fromSpecs);
+
+  return Array.from(new Set(merged));
+}
+
+/**
+ * Execute multi-spec work through orchestrate mode.
+ *
+ * @param {object} options
+ * @param {string[]} options.specTargets
+ * @param {string} options.projectPath
+ * @param {object} options.commandOptions
+ * @param {Function} options.runOrchestration
+ * @param {string} options.commandLabel
+ * @param {string} options.nextActionLabel
+ * @returns {Promise<object>}
+ */
+async function runMultiSpecViaOrchestrate(options = {}) {
+  const {
+    specTargets,
+    projectPath,
+    commandOptions,
+    runOrchestration,
+    commandLabel,
+    nextActionLabel
+  } = options;
+
+  const orchestrationResult = await runOrchestration({
+    specs: specTargets.join(','),
+    maxParallel: commandOptions.maxParallel,
+    json: false,
+    silent: true
+  }, {
+    workspaceRoot: projectPath
+  });
+
+  const result = {
+    mode: 'orchestrate',
+    spec_ids: specTargets,
+    status: orchestrationResult.status,
+    orchestrate_result: orchestrationResult,
+    next_actions: [
+      nextActionLabel,
+      'Use kse orchestrate status to inspect live orchestration state.'
+    ]
+  };
+
+  if (commandOptions.out) {
+    const outPath = path.isAbsolute(commandOptions.out)
+      ? commandOptions.out
+      : path.join(projectPath, commandOptions.out);
+    await fs.ensureDir(path.dirname(outPath));
+    await fs.writeJson(outPath, result, { spaces: 2 });
+    result.output_file = outPath;
+  }
+
+  if (commandOptions.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(chalk.blue('🚀') + ` ${commandLabel} defaulted to orchestrate mode for ${specTargets.length} specs.`);
+    console.log(chalk.gray(`  Specs: ${specTargets.join(', ')}`));
+    console.log(chalk.gray(`  Status: ${orchestrationResult.status}`));
+  }
+
+  return result;
+}
+
+module.exports = {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+};
+

package/lib/spec/pipeline/constants.js

@@ -0,0 +1,6 @@
+const STAGE_ORDER = ['requirements', 'design', 'tasks', 'gate'];
+
+module.exports = {
+  STAGE_ORDER
+};
+

package/lib/spec/pipeline/stage-adapters.js

@@ -0,0 +1,118 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { runSpecBootstrap } = require('../../commands/spec-bootstrap');
+const { runSpecGate } = require('../../commands/spec-gate');
+
+function createDefaultStageAdapters(projectPath = process.cwd()) {
+  return {
+    requirements: async context => {
+      const specDir = path.join(projectPath, '.kiro', 'specs', context.specId);
+      const requirementsPath = path.join(specDir, 'requirements.md');
+
+      if (!await fs.pathExists(requirementsPath)) {
+        await runSpecBootstrap({
+          name: context.specId,
+          nonInteractive: true,
+          profile: 'pipeline',
+          dryRun: false,
+          json: false
+        }, {
+          projectPath
+        });
+
+        return {
+          success: true,
+          details: {
+            action: 'bootstrap-generated'
+          }
+        };
+      }
+
+      return {
+        success: true,
+        details: {
+          action: 'requirements-existing'
+        }
+      };
+    },
+
+    design: async context => {
+      const designPath = path.join(projectPath, '.kiro', 'specs', context.specId, 'design.md');
+      const exists = await fs.pathExists(designPath);
+
+      if (!exists) {
+        await runSpecBootstrap({
+          name: context.specId,
+          nonInteractive: true,
+          profile: 'pipeline',
+          dryRun: false,
+          json: false
+        }, {
+          projectPath
+        });
+      }
+
+      return {
+        success: true,
+        warnings: exists ? [] : ['design.md was created from bootstrap defaults'],
+        details: {
+          action: exists ? 'design-existing' : 'design-generated'
+        }
+      };
+    },
+
+    tasks: async context => {
+      const tasksPath = path.join(projectPath, '.kiro', 'specs', context.specId, 'tasks.md');
+      const exists = await fs.pathExists(tasksPath);
+
+      if (!exists) {
+        await runSpecBootstrap({
+          name: context.specId,
+          nonInteractive: true,
+          profile: 'pipeline',
+          dryRun: false,
+          json: false
+        }, {
+          projectPath
+        });
+      }
+
+      return {
+        success: true,
+        warnings: exists ? [] : ['tasks.md was created from bootstrap defaults'],
+        details: {
+          action: exists ? 'tasks-existing' : 'tasks-generated'
+        }
+      };
+    },
+
+    gate: async context => {
+      const gateResult = await runSpecGate({
+        spec: context.specId,
+        json: false,
+        strict: !!context.strict,
+        out: context.gateOut,
+        silent: true
+      }, {
+        projectPath
+      });
+
+      const success = gateResult.decision === 'go' || gateResult.decision === 'conditional-go';
+
+      return {
+        success,
+        warnings: gateResult.warnings ? gateResult.warnings.map(item => item.message) : [],
+        details: {
+          decision: gateResult.decision,
+          score: gateResult.score,
+          failed_checks: gateResult.failed_checks || []
+        }
+      };
+    }
+  };
+}
+
+module.exports = {
+  createDefaultStageAdapters
+};
+

package/lib/spec/pipeline/stage-runner.js

@@ -0,0 +1,146 @@
+const { STAGE_ORDER } = require('./constants');
+
+class StageRunner {
+  constructor(options = {}) {
+    this.stateStore = options.stateStore;
+    this.adapters = options.adapters || {};
+  }
+
+  async run(context) {
+    const selectedStages = this._selectStages({
+      fromStage: context.fromStage,
+      toStage: context.toStage
+    });
+
+    const stageResults = [];
+
+    for (const stageName of selectedStages) {
+      if (context.resume && this._isCompleted(context.state, stageName)) {
+        stageResults.push({
+          name: stageName,
+          status: 'skipped',
+          reason: 'already-completed'
+        });
+        continue;
+      }
+
+      const adapter = this.adapters[stageName];
+      if (typeof adapter !== 'function') {
+        const error = `No adapter registered for stage: ${stageName}`;
+        await this.stateStore.markStageResult(context.state, stageName, {
+          status: 'failed',
+          error
+        });
+        stageResults.push({ name: stageName, status: 'failed', error });
+        return {
+          status: 'failed',
+          stageResults,
+          failure: { stage: stageName, error }
+        };
+      }
+
+      await this.stateStore.markStageStart(context.state, stageName);
+
+      let adapterResult;
+      try {
+        adapterResult = context.dryRun
+          ? { success: true, details: { dry_run: true }, warnings: [] }
+          : await adapter(context);
+      } catch (error) {
+        adapterResult = {
+          success: false,
+          error: error.message,
+          warnings: []
+        };
+      }
+
+      const normalized = this._normalizeResult(adapterResult);
+      const status = normalized.success ? (normalized.warnings.length > 0 ? 'warning' : 'completed') : 'failed';
+
+      await this.stateStore.markStageResult(context.state, stageName, {
+        status,
+        warnings: normalized.warnings,
+        error: normalized.error,
+        output: normalized.details
+      });
+
+      stageResults.push({
+        name: stageName,
+        status,
+        warnings: normalized.warnings,
+        error: normalized.error,
+        output: normalized.details
+      });
+
+      if (status === 'failed' && context.failFast) {
+        return {
+          status: 'failed',
+          stageResults,
+          failure: {
+            stage: stageName,
+            error: normalized.error || 'stage failed'
+          }
+        };
+      }
+
+      if (status === 'warning' && !context.continueOnWarning) {
+        return {
+          status: 'failed',
+          stageResults,
+          failure: {
+            stage: stageName,
+            error: 'warning encountered with continue-on-warning disabled'
+          }
+        };
+      }
+    }
+
+    return {
+      status: 'completed',
+      stageResults,
+      failure: null
+    };
+  }
+
+  _selectStages(range = {}) {
+    const fromStage = range.fromStage || STAGE_ORDER[0];
+    const toStage = range.toStage || STAGE_ORDER[STAGE_ORDER.length - 1];
+
+    const fromIndex = STAGE_ORDER.indexOf(fromStage);
+    const toIndex = STAGE_ORDER.indexOf(toStage);
+
+    if (fromIndex < 0 || toIndex < 0 || fromIndex > toIndex) {
+      throw new Error(`Invalid stage range: from=${fromStage}, to=${toStage}`);
+    }
+
+    return STAGE_ORDER.slice(fromIndex, toIndex + 1);
+  }
+
+  _normalizeResult(result) {
+    if (!result || typeof result !== 'object') {
+      return {
+        success: false,
+        warnings: [],
+        error: 'Invalid stage result',
+        details: null
+      };
+    }
+
+    return {
+      success: !!result.success,
+      warnings: Array.isArray(result.warnings) ? result.warnings : [],
+      error: result.error || null,
+      details: result.details || null
+    };
+  }
+
+  _isCompleted(state, stageName) {
+    const stage = (state.stages || []).find(item => item.name === stageName);
+    return !!stage && stage.status === 'completed';
+  }
+}
+
+module.exports = {
+  StageRunner
+};
+

package/lib/spec/pipeline/state-store.js

@@ -0,0 +1,119 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { randomUUID } = require('crypto');
+
+class PipelineStateStore {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  getStateDir(specId) {
+    return path.join(this.projectPath, '.kiro', 'state', 'spec-pipeline', specId);
+  }
+
+  getRunPath(specId, runId) {
+    return path.join(this.getStateDir(specId), `${runId}.json`);
+  }
+
+  getLatestPath(specId) {
+    return path.join(this.getStateDir(specId), 'latest.json');
+  }
+
+  async create(specId, options = {}) {
+    const runId = options.runId || randomUUID();
+    const state = {
+      spec_id: specId,
+      run_id: runId,
+      status: 'running',
+      strategy: {
+        fail_fast: options.failFast !== false,
+        continue_on_warning: !!options.continueOnWarning
+      },
+      stages: [],
+      started_at: new Date().toISOString(),
+      ended_at: null
+    };
+
+    await this.save(state);
+    return state;
+  }
+
+  async save(state) {
+    const runPath = this.getRunPath(state.spec_id, state.run_id);
+    const latestPath = this.getLatestPath(state.spec_id);
+
+    await fs.ensureDir(path.dirname(runPath));
+    await fs.writeJson(runPath, state, { spaces: 2 });
+    await fs.writeJson(latestPath, {
+      spec_id: state.spec_id,
+      run_id: state.run_id,
+      updated_at: new Date().toISOString()
+    }, { spaces: 2 });
+
+    return runPath;
+  }
+
+  async loadLatest(specId) {
+    const latestPath = this.getLatestPath(specId);
+    if (!await fs.pathExists(latestPath)) {
+      return null;
+    }
+
+    const latest = await fs.readJson(latestPath);
+    const runPath = this.getRunPath(specId, latest.run_id);
+    if (!await fs.pathExists(runPath)) {
+      return null;
+    }
+
+    return fs.readJson(runPath);
+  }
+
+  async markStageStart(state, stageName) {
+    const stage = this._getOrCreateStage(state, stageName);
+    stage.status = 'running';
+    stage.started_at = new Date().toISOString();
+    stage.ended_at = null;
+    stage.error = null;
+    stage.warnings = [];
+
+    await this.save(state);
+  }
+
+  async markStageResult(state, stageName, result) {
+    const stage = this._getOrCreateStage(state, stageName);
+    stage.status = result.status;
+    stage.ended_at = new Date().toISOString();
+    stage.error = result.error || null;
+    stage.warnings = result.warnings || [];
+    stage.output = result.output || null;
+
+    await this.save(state);
+  }
+
+  async markFinished(state, status) {
+    state.status = status;
+    state.ended_at = new Date().toISOString();
+    await this.save(state);
+  }
+
+  _getOrCreateStage(state, stageName) {
+    let stage = state.stages.find(item => item.name === stageName);
+    if (!stage) {
+      stage = {
+        name: stageName,
+        status: 'pending',
+        started_at: null,
+        ended_at: null,
+        warnings: []
+      };
+      state.stages.push(stage);
+    }
+
+    return stage;
+  }
+}
+
+module.exports = {
+  PipelineStateStore
+};
+

package/lib/spec-gate/engine/gate-engine.js

@@ -0,0 +1,165 @@
+const { randomUUID } = require('crypto');
+
+class GateEngine {
+  constructor(options = {}) {
+    this.registry = options.registry;
+    this.policy = options.policy;
+  }
+
+  async evaluate(input = {}) {
+    const specId = input.specId;
+    const runId = input.runId || randomUUID();
+    const startedAt = new Date().toISOString();
+
+    const policyRules = (this.policy && this.policy.rules) || {};
+    const enabledRules = this.registry.listEnabled(policyRules);
+
+    const rules = [];
+    const failedChecks = [];
+    const warnings = [];
+
+    let weightedScore = 0;
+    let totalWeight = 0;
+    let hardFailTriggered = false;
+
+    for (const rule of enabledRules) {
+      const policyEntry = policyRules[rule.id] || {};
+      const weight = Number(policyEntry.weight || 0);
+      const hardFail = !!policyEntry.hard_fail;
+
+      totalWeight += weight;
+      const execution = await rule.execute({
+        specId,
+        runId,
+        policy: this.policy
+      });
+
+      const passed = !!execution.passed;
+      const ratio = this._normalizeRatio(execution.ratio);
+      const ruleScore = passed ? weight : Number((weight * ratio).toFixed(2));
+
+      if (!passed) {
+        failedChecks.push({
+          id: rule.id,
+          hard_fail: hardFail,
+          details: execution.details || {}
+        });
+      }
+
+      if (hardFail && !passed) {
+        hardFailTriggered = true;
+      }
+
+      if (Array.isArray(execution.warnings) && execution.warnings.length > 0) {
+        warnings.push(...execution.warnings.map(message => ({ id: rule.id, message })));
+      }
+
+      weightedScore += ruleScore;
+
+      rules.push({
+        id: rule.id,
+        passed,
+        score: ruleScore,
+        max_score: weight,
+        hard_fail: hardFail,
+        warnings: execution.warnings || [],
+        details: execution.details || {}
+      });
+    }
+
+    const score = totalWeight > 0
+      ? Math.round((weightedScore / totalWeight) * 100)
+      : 0;
+
+    const decision = this._decide({
+      score,
+      hardFailTriggered,
+      warnings
+    });
+
+    const nextActions = this._buildNextActions(decision, failedChecks, warnings);
+    const endedAt = new Date().toISOString();
+
+    return {
+      spec_id: specId,
+      run_id: runId,
+      decision,
+      score,
+      rules,
+      failed_checks: failedChecks,
+      warnings,
+      next_actions: nextActions,
+      policy_snapshot: {
+        thresholds: this.policy.thresholds,
+        strict_mode: this.policy.strict_mode
+      },
+      started_at: startedAt,
+      ended_at: endedAt
+    };
+  }
+
+  _normalizeRatio(value) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+      return 0;
+    }
+
+    if (value < 0) {
+      return 0;
+    }
+
+    if (value > 1) {
+      return 1;
+    }
+
+    return value;
+  }
+
+  _decide(context) {
+    const thresholds = this.policy.thresholds || {};
+    const goThreshold = Number(thresholds.go || 90);
+    const conditionalThreshold = Number(thresholds.conditional_go || 70);
+    const warningAsFailure = !!(this.policy.strict_mode && this.policy.strict_mode.warning_as_failure);
+
+    if (context.hardFailTriggered) {
+      return 'no-go';
+    }
+
+    if (warningAsFailure && context.warnings.length > 0) {
+      return 'no-go';
+    }
+
+    if (context.score >= goThreshold) {
+      return 'go';
+    }
+
+    if (context.score >= conditionalThreshold) {
+      return 'conditional-go';
+    }
+
+    return 'no-go';
+  }
+
+  _buildNextActions(decision, failedChecks, warnings) {
+    if (decision === 'go') {
+      return ['Proceed to implementation and keep evidence attached to Spec artifacts.'];
+    }
+
+    const actions = [];
+
+    if (failedChecks.length > 0) {
+      actions.push(`Fix failed checks: ${failedChecks.map(item => item.id).join(', ')}`);
+    }
+
+    if (warnings.length > 0) {
+      actions.push('Review warnings and decide whether to re-run with relaxed strict mode.');
+    }
+
+    actions.push('Re-run gate after remediation and attach latest gate report.');
+    return actions;
+  }
+}
+
+module.exports = {
+  GateEngine
+};
+

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

@@ -0,0 +1,22 @@
+const DEFAULT_GATE_POLICY = {
+  version: 1,
+  thresholds: {
+    go: 90,
+    conditional_go: 70
+  },
+  strict_mode: {
+    warning_as_failure: true
+  },
+  rules: {
+    mandatory: { enabled: true, weight: 30, hard_fail: true },
+    tests: { enabled: true, weight: 25, hard_fail: true },
+    docs: { enabled: true, weight: 15, hard_fail: false },
+    config_consistency: { enabled: true, weight: 15, hard_fail: false },
+    traceability: { enabled: true, weight: 15, hard_fail: false }
+  }
+};
+
+module.exports = {
+  DEFAULT_GATE_POLICY
+};
+