kiro-spec-engine 1.45.13 → 1.46.0

package/lib/commands/spec-gate.js

@@ -0,0 +1,157 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { PolicyLoader } = require('../spec-gate/policy/policy-loader');
+const { RuleRegistry } = require('../spec-gate/rules/rule-registry');
+const { createDefaultRules } = require('../spec-gate/rules/default-rules');
+const { GateEngine } = require('../spec-gate/engine/gate-engine');
+const { ResultEmitter } = require('../spec-gate/result-emitter');
+
+async function runSpecGate(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const specTargets = parseSpecTargets(options);
+
+  if (specTargets.length === 0) {
+    throw new Error('Either --spec or --specs is required');
+  }
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec gate',
+      nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+    });
+  }
+
+  const specId = specTargets[0];
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specId);
+  if (!await fs.pathExists(specPath)) {
+    throw new Error(`Spec not found: ${specId}`);
+  }
+
+  const policyLoader = dependencies.policyLoader || new PolicyLoader(projectPath);
+  const policy = dependencies.policy || await policyLoader.load({
+    policy: options.policy,
+    strict: options.strict
+  });
+
+  const registry = dependencies.registry || new RuleRegistry(createDefaultRules(projectPath));
+  const engine = dependencies.engine || new GateEngine({
+    registry,
+    policy
+  });
+
+  const result = await engine.evaluate({ specId });
+  const emitter = dependencies.emitter || new ResultEmitter(projectPath);
+  const emitted = await emitter.emit(result, {
+    json: options.json,
+    out: options.out,
+    silent: options.silent
+  });
+
+  return {
+    ...result,
+    report_path: emitted.outputPath
+  };
+}
+
+async function generateSpecGatePolicyTemplate(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const loader = dependencies.policyLoader || new PolicyLoader(projectPath);
+  const template = loader.getTemplate();
+
+  const outputPath = options.out
+    ? (path.isAbsolute(options.out) ? options.out : path.join(projectPath, options.out))
+    : path.join(projectPath, '.kiro', 'config', 'spec-gate-policy.template.json');
+
+  await fs.ensureDir(path.dirname(outputPath));
+  await fs.writeJson(outputPath, template, { spaces: 2 });
+
+  if (!options.silent) {
+    console.log(chalk.green('✅ Spec gate policy template generated:'));
+    console.log(`  ${outputPath}`);
+  }
+
+  return {
+    success: true,
+    outputPath
+  };
+}
+
+function registerSpecGateCommand(program) {
+  const specGate = program
+    .command('spec-gate')
+    .description('Run standardized Spec gate checks (use: kse spec gate)');
+
+  specGate
+    .command('run')
+    .description('Execute gate checks for one or more Specs')
+    .option('--spec <name>', 'Single Spec identifier')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--policy <path>', 'Policy JSON path')
+    .option('--strict', 'Enable strict mode override')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--out <path>', 'Write JSON result to file')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .action(async options => {
+      try {
+        await runSpecGate(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec gate failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+
+  specGate
+    .command('policy-template')
+    .description('Generate policy template JSON for Spec gate')
+    .option('--out <path>', 'Template output path')
+    .action(async options => {
+      try {
+        await generateSpecGatePolicyTemplate(options);
+      } catch (error) {
+        console.error(chalk.red('❌ Failed to generate policy template:'), error.message);
+        process.exit(1);
+      }
+    });
+}
+
+async function _runGateInOrchestrateMode(specTargets, options, dependencies) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+
+  return runMultiSpecViaOrchestrate({
+    specTargets,
+    projectPath,
+    commandOptions: options,
+    runOrchestration: executeOrchestration,
+    commandLabel: 'Multi-spec gate',
+    nextActionLabel: 'Multi-spec gate execution defaulted to orchestrate mode.'
+  });
+}
+
+function _parseSpecTargets(options = {}) {
+  return parseSpecTargets(options);
+}
+
+module.exports = {
+  registerSpecGateCommand,
+  runSpecGate,
+  generateSpecGatePolicyTemplate,
+  _parseSpecTargets
+};

package/lib/commands/spec-pipeline.js

@@ -0,0 +1,205 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { PipelineStateStore } = require('../spec/pipeline/state-store');
+const { StageRunner } = require('../spec/pipeline/stage-runner');
+const { createDefaultStageAdapters } = require('../spec/pipeline/stage-adapters');
+
+async function runSpecPipeline(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const specTargets = parseSpecTargets(options);
+  if (specTargets.length === 0) {
+    throw new Error('Either --spec or --specs is required');
+  }
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec pipeline',
+      nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+    });
+  }
+
+  const specId = specTargets[0];
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specId);
+  if (!await fs.pathExists(specPath)) {
+    throw new Error(`Spec not found: ${specId}`);
+  }
+
+  const stateStore = dependencies.stateStore || new PipelineStateStore(projectPath);
+  const adapters = dependencies.adapters || createDefaultStageAdapters(projectPath);
+  const stageRunner = dependencies.stageRunner || new StageRunner({
+    stateStore,
+    adapters
+  });
+
+  let state;
+  if (options.resume) {
+    state = await stateStore.loadLatest(specId);
+  }
+
+  if (!state) {
+    state = await stateStore.create(specId, {
+      failFast: options.failFast !== false,
+      continueOnWarning: !!options.continueOnWarning
+    });
+  }
+
+  const runContext = {
+    specId,
+    runId: state.run_id,
+    fromStage: options.fromStage,
+    toStage: options.toStage,
+    dryRun: !!options.dryRun,
+    resume: !!options.resume,
+    failFast: options.failFast !== false,
+    continueOnWarning: !!options.continueOnWarning,
+    strict: !!options.strict,
+    gateOut: options.gateOut,
+    state
+  };
+
+  const execution = await stageRunner.run(runContext);
+  await stateStore.markFinished(state, execution.status);
+
+  const result = {
+    spec_id: specId,
+    run_id: state.run_id,
+    status: execution.status,
+    stage_results: execution.stageResults,
+    failure: execution.failure,
+    next_actions: buildNextActions(execution),
+    state_file: path.relative(projectPath, stateStore.getRunPath(specId, state.run_id))
+  };
+
+  if (options.out) {
+    const outPath = path.isAbsolute(options.out)
+      ? options.out
+      : path.join(projectPath, options.out);
+    await fs.ensureDir(path.dirname(outPath));
+    await fs.writeJson(outPath, result, { spaces: 2 });
+    result.output_file = outPath;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printResult(result);
+  }
+
+  return result;
+}
+
+function registerSpecPipelineCommand(program) {
+  const pipeline = program
+    .command('spec-pipeline')
+    .description('Run Spec workflow pipeline (use: kse spec pipeline run)');
+
+  pipeline
+    .command('run')
+    .description('Execute pipeline stages for one or more Specs')
+    .option('--spec <name>', 'Single Spec identifier')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--from-stage <stage>', 'Start stage (requirements/design/tasks/gate)')
+    .option('--to-stage <stage>', 'End stage (requirements/design/tasks/gate)')
+    .option('--resume', 'Resume from latest unfinished stage state')
+    .option('--dry-run', 'Preview pipeline execution without writing stage outputs')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--out <path>', 'Write pipeline result JSON to file')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .option('--continue-on-warning', 'Continue when stage returns warnings')
+    .option('--no-fail-fast', 'Do not stop immediately on failed stage')
+    .option('--strict', 'Enable strict mode for downstream gate stage')
+    .option('--gate-out <path>', 'Output path for nested gate stage report')
+    .action(async options => {
+      try {
+        await runSpecPipeline(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec pipeline failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+function printResult(result) {
+  const statusColor = result.status === 'completed' ? chalk.green : chalk.red;
+
+  console.log(chalk.red('🔥') + ' Spec Workflow Pipeline');
+  console.log();
+  console.log(`${chalk.gray('Spec:')} ${result.spec_id}`);
+  console.log(`${chalk.gray('Run:')} ${result.run_id}`);
+  console.log(`${chalk.gray('Status:')} ${statusColor(result.status)}`);
+  console.log();
+
+  console.log(chalk.bold('Stage Results'));
+  result.stage_results.forEach(stage => {
+    const icon = stage.status === 'completed'
+      ? chalk.green('✓')
+      : stage.status === 'warning'
+        ? chalk.yellow('!')
+        : stage.status === 'skipped'
+          ? chalk.gray('→')
+          : chalk.red('✗');
+    console.log(`  ${icon} ${stage.name}: ${stage.status}`);
+  });
+
+  if (result.next_actions.length > 0) {
+    console.log();
+    console.log(chalk.bold('Next Actions'));
+    result.next_actions.forEach(action => console.log(`  - ${action}`));
+  }
+}
+
+function buildNextActions(execution) {
+  if (execution.status === 'completed') {
+    return ['Review pipeline output and continue implementation on completed Spec stages.'];
+  }
+
+  if (execution.failure && execution.failure.stage) {
+    return [
+      `Resolve failure at stage: ${execution.failure.stage}`,
+      'Use --resume to continue from the last unfinished stage after remediation.'
+    ];
+  }
+
+  return ['Inspect stage_results for failure details and re-run pipeline.'];
+}
+
+async function _runPipelineInOrchestrateMode(specTargets, options, dependencies) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+
+  return runMultiSpecViaOrchestrate({
+    specTargets,
+    projectPath,
+    commandOptions: options,
+    runOrchestration: executeOrchestration,
+    commandLabel: 'Multi-spec pipeline',
+    nextActionLabel: 'Multi-spec execution defaulted to orchestrate mode.'
+  });
+}
+
+function _parseSpecTargets(options = {}) {
+  return parseSpecTargets(options);
+}
+
+module.exports = {
+  registerSpecPipelineCommand,
+  runSpecPipeline,
+  _parseSpecTargets
+};

package/lib/spec/bootstrap/context-collector.js

@@ -0,0 +1,48 @@
+const fs = require('fs-extra');
+const path = require('path');
+
+class ContextCollector {
+  constructor(projectPath = process.cwd()) {
+    this.projectPath = projectPath;
+  }
+
+  async collect() {
+    const kiroDir = path.join(this.projectPath, '.kiro');
+    const specsDir = path.join(kiroDir, 'specs');
+    const hasKiro = await fs.pathExists(kiroDir);
+    const existingSpecs = await this._listSpecs(specsDir);
+
+    return {
+      projectPath: this.projectPath,
+      hasKiro,
+      specsDir,
+      existingSpecs,
+      totalSpecs: existingSpecs.length,
+      preferredLanguage: this._detectLanguagePreference()
+    };
+  }
+
+  async _listSpecs(specsDir) {
+    if (!await fs.pathExists(specsDir)) {
+      return [];
+    }
+
+    const entries = await fs.readdir(specsDir, { withFileTypes: true });
+    return entries
+      .filter(entry => entry.isDirectory())
+      .map(entry => entry.name)
+      .sort((left, right) => left.localeCompare(right));
+  }
+
+  _detectLanguagePreference() {
+    const lang = `${process.env.KSE_LANG || process.env.LANG || ''}`.toLowerCase();
+    if (lang.includes('zh')) {
+      return 'zh';
+    }
+
+    return 'en';
+  }
+}
+
+module.exports = { ContextCollector };
+

package/lib/spec/bootstrap/draft-generator.js

@@ -0,0 +1,158 @@
+class DraftGenerator {
+  generate(input = {}) {
+    const specName = input.specName;
+    const profile = input.profile || 'general';
+    const template = input.template || 'default';
+    const context = input.context || {};
+    const answers = input.answers || {};
+
+    const requirementIds = ['Requirement 1', 'Requirement 2', 'Requirement 3'];
+    const designIds = ['Design 1', 'Design 2', 'Design 3'];
+
+    const requirements = this._buildRequirements(specName, profile, template, answers);
+    const design = this._buildDesign(specName, profile, template, requirementIds, designIds, answers);
+    const tasks = this._buildTasks(requirementIds, designIds);
+
+    return {
+      requirements,
+      design,
+      tasks,
+      metadata: {
+        profile,
+        template,
+        projectPath: context.projectPath,
+        preferredLanguage: context.preferredLanguage || 'en',
+        existingSpecCount: context.totalSpecs || 0,
+        mapping: {
+          requirements: requirementIds,
+          design: designIds,
+          taskCount: 6
+        }
+      }
+    };
+  }
+
+  _buildRequirements(specName, profile, template, answers) {
+    return `# Requirements Document
+
+## Introduction
+
+This Spec bootstrap draft was generated for ${specName} with profile ${profile} and template hint ${template}.
+
+## Context Snapshot
+
+- Problem statement: ${answers.problemStatement}
+- Primary flow: ${answers.primaryFlow}
+- Verification plan: ${answers.verificationPlan}
+
+## Requirements
+
+### Requirement 1: Establish command entry
+
+**User Story:** As a user, I want one command to initialize a complete Spec draft.
+
+#### Acceptance Criteria
+
+1. THE CLI SHALL expose an entry command for bootstrap generation
+2. THE command SHALL support explicit naming and non-interactive execution
+
+### Requirement 2: Collect minimum context
+
+**User Story:** As an implementer, I want the wizard to use project context with a controlled question set.
+
+#### Acceptance Criteria
+
+1. THE SYSTEM SHALL collect project metadata and existing Spec inventory
+2. THE wizard SHALL keep the questionnaire small and default-driven
+3. WHEN non-interactive mode is enabled THEN generation SHALL rely on arguments and defaults only
+
+### Requirement 3: Generate traceable draft docs
+
+**User Story:** As a team member, I want requirements/design/tasks to stay mapped and auditable.
+
+#### Acceptance Criteria
+
+1. THE SYSTEM SHALL output requirements.md, design.md, and tasks.md together
+2. THE output SHALL contain requirement-design-task mapping references
+3. THE output SHALL capture generation trace information for governance and audit
+`;
+  }
+
+  _buildDesign(specName, profile, template, requirementIds, designIds, answers) {
+    return `# Design Document
+
+## Overview
+
+This design document defines the bootstrap generation flow for ${specName}.
+
+- Profile: ${profile}
+- Template hint: ${template}
+
+## Requirement Mapping
+
+| Requirement | Design Component | Notes |
+| --- | --- | --- |
+| ${requirementIds[0]} | ${designIds[0]} | CLI entry and argument handling |
+| ${requirementIds[1]} | ${designIds[1]} | Context collector and questionnaire |
+| ${requirementIds[2]} | ${designIds[2]} | Draft generation and trace output |
+
+## Design Components
+
+### Design 1: Bootstrap command orchestration
+
+- Parse name/template/profile/non-interactive/dry-run/json options
+- Handle write mode and dry-run preview mode consistently
+
+### Design 2: Context and prompt pipeline
+
+- Collect project metadata and existing Spec list
+- Keep questionnaire minimal with defaults
+- Input guidance: ${answers.primaryFlow}
+
+### Design 3: Draft and trace emitter
+
+- Generate linked requirements/design/tasks content
+- Emit trace metadata (template, profile, key parameters)
+- Validation guidance: ${answers.verificationPlan}
+`;
+  }
+
+  _buildTasks(requirementIds, designIds) {
+    return `# Implementation Tasks
+
+## Task List
+
+- [ ] 1. Implement command entry and option parsing
+  - **Requirement**: ${requirementIds[0]}
+  - **Design**: ${designIds[0]}
+  - **Validation**: Acceptance Criteria 1.1, 1.2
+
+- [ ] 2. Implement dry-run and write-mode behavior
+  - **Requirement**: ${requirementIds[0]}
+  - **Design**: ${designIds[0]}
+  - **Validation**: Acceptance Criteria 1.1
+
+- [ ] 3. Implement context collector
+  - **Requirement**: ${requirementIds[1]}
+  - **Design**: ${designIds[1]}
+  - **Validation**: Acceptance Criteria 2.1
+
+- [ ] 4. Implement minimal questionnaire with defaults
+  - **Requirement**: ${requirementIds[1]}
+  - **Design**: ${designIds[1]}
+  - **Validation**: Acceptance Criteria 2.2, 2.3
+
+- [ ] 5. Implement linked document generation
+  - **Requirement**: ${requirementIds[2]}
+  - **Design**: ${designIds[2]}
+  - **Validation**: Acceptance Criteria 3.1, 3.2
+
+- [ ] 6. Implement trace output and JSON mode
+  - **Requirement**: ${requirementIds[2]}
+  - **Design**: ${designIds[2]}
+  - **Validation**: Acceptance Criteria 3.3
+`;
+  }
+}
+
+module.exports = { DraftGenerator };

package/lib/spec/bootstrap/questionnaire-engine.js

@@ -0,0 +1,70 @@
+const inquirer = require('inquirer');
+
+const DEFAULT_ANSWERS = {
+  problemStatement: 'Define the feature scope and the expected business outcome.',
+  primaryFlow: 'Capture user flow, data flow, and observable outputs.',
+  verificationPlan: 'Define verification checks and acceptance coverage.'
+};
+
+class QuestionnaireEngine {
+  constructor(options = {}) {
+    this.maxQuestions = options.maxQuestions || 3;
+    this.prompt = options.prompt || inquirer.prompt;
+  }
+
+  async collect(options = {}) {
+    const defaults = this._buildDefaults(options);
+
+    if (options.nonInteractive) {
+      return defaults;
+    }
+
+    const questions = [
+      {
+        type: 'input',
+        name: 'specName',
+        message: 'Spec name (for example: 112-00-feature-name):',
+        default: defaults.specName,
+        validate: input => input && input.trim() ? true : 'Spec name is required'
+      },
+      {
+        type: 'input',
+        name: 'problemStatement',
+        message: 'What problem should this Spec solve?',
+        default: defaults.problemStatement
+      },
+      {
+        type: 'input',
+        name: 'primaryFlow',
+        message: 'What is the primary implementation flow?',
+        default: defaults.primaryFlow
+      },
+      {
+        type: 'input',
+        name: 'verificationPlan',
+        message: 'How should this Spec be validated?',
+        default: defaults.verificationPlan
+      }
+    ].slice(0, this.maxQuestions + 1);
+
+    const answers = await this.prompt(questions);
+    return {
+      ...defaults,
+      ...answers,
+      questionCount: questions.length
+    };
+  }
+
+  _buildDefaults(options = {}) {
+    return {
+      specName: options.specName || '',
+      problemStatement: options.problemStatement || DEFAULT_ANSWERS.problemStatement,
+      primaryFlow: options.primaryFlow || DEFAULT_ANSWERS.primaryFlow,
+      verificationPlan: options.verificationPlan || DEFAULT_ANSWERS.verificationPlan,
+      questionCount: 0
+    };
+  }
+}
+
+module.exports = { QuestionnaireEngine, DEFAULT_ANSWERS };
+

package/lib/spec/bootstrap/trace-emitter.js

@@ -0,0 +1,59 @@
+const chalk = require('chalk');
+
+class TraceEmitter {
+  emit(result, options = {}) {
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(chalk.red('🔥') + ' Spec Bootstrap Wizard');
+    console.log();
+    console.log(`${chalk.gray('Spec:')} ${result.specName}`);
+    console.log(`${chalk.gray('Mode:')} ${result.dryRun ? 'dry-run' : 'write'}`);
+    console.log(`${chalk.gray('Template:')} ${result.trace.template}`);
+    console.log(`${chalk.gray('Profile:')} ${result.trace.profile}`);
+    console.log();
+
+    if (result.dryRun) {
+      console.log(chalk.yellow('⚠ Dry-run mode: no files were written.'));
+      console.log();
+      this._printPreview(result.preview || {});
+    } else {
+      console.log(chalk.green('✅ Draft files generated:'));
+      Object.values(result.files || {}).forEach(filePath => {
+        console.log(`  - ${filePath}`);
+      });
+    }
+
+    console.log();
+    console.log(chalk.blue('📌 Trace Summary'));
+    console.log(`  - existing specs: ${result.trace.context.totalSpecs}`);
+    console.log(`  - preferred language: ${result.trace.context.preferredLanguage}`);
+    console.log(`  - non-interactive: ${result.trace.parameters.nonInteractive}`);
+  }
+
+  _printPreview(preview) {
+    const sections = ['requirements', 'design', 'tasks'];
+
+    sections.forEach(section => {
+      const content = preview[section];
+      if (!content) {
+        return;
+      }
+
+      const lines = content
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .slice(0, 5);
+
+      console.log(chalk.cyan(`--- ${section}.md preview ---`));
+      lines.forEach(line => console.log(`  ${line}`));
+      console.log('  ...');
+      console.log();
+    });
+  }
+}
+
+module.exports = { TraceEmitter };
+