scene-capability-engine 3.0.0

package/lib/scene-runtime/templates/scene-template-erp-query-v0.1.yaml

@@ -0,0 +1,28 @@
+apiVersion: kse.scene/v0.2
+kind: scene
+metadata:
+  obj_id: scene.template.erp-order-query
+  obj_version: 0.2.0
+  title: ERP Order Query Template
+spec:
+  domain: erp
+  intent:
+    goal: Query order detail and return normalized response
+  model_scope:
+    read:
+      - moqui.OrderHeader.orderId
+      - moqui.OrderHeader.statusId
+    write: []
+  capability_contract:
+    bindings:
+      - type: query
+        ref: spec.erp.order-query-service
+        timeout_ms: 2000
+        retry: 0
+  governance_contract:
+    risk_level: low
+    approval:
+      required: false
+    idempotency:
+      required: true
+      key: orderId

package/lib/scene-runtime/templates/scene-template-hybrid-shadow-v0.1.yaml

@@ -0,0 +1,34 @@
+apiVersion: kse.scene/v0.2
+kind: scene
+metadata:
+  obj_id: scene.template.hybrid-pick-shadow
+  obj_version: 0.2.0
+  title: Hybrid Pick Shadow Template
+spec:
+  domain: hybrid
+  intent:
+    goal: Simulate ERP reserve and robot mission dispatch in dry_run
+  model_scope:
+    read:
+      - moqui.OrderHeader.orderId
+    write:
+      - moqui.OrderItem.statusId
+  capability_contract:
+    bindings:
+      - type: service
+        ref: spec.erp.reserve-pick-items
+        side_effect: true
+        timeout_ms: 3000
+        retry: 0
+      - type: adapter
+        ref: spec.robot.dispatch-pick-mission
+        side_effect: true
+        timeout_ms: 6000
+        retry: 0
+  governance_contract:
+    risk_level: high
+    approval:
+      required: true
+    idempotency:
+      required: true
+      key: orderId

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 };
+

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
+};
+