kiro-spec-engine 1.47.6 → 1.47.7

package/docs/331-poc-adaptation-roadmap.md

@@ -0,0 +1,41 @@
+# 331-poc 适配持续推进路线图（KSE 侧）
+
+> 范围：`kiro-spec-engine` 侧围绕 331-poc handoff 的持续适配工作，不包含 331 业务实现本身。
+
+## 已完成（本轮）
+
+1. 新增 handoff 自动化命令：
+   - `kse auto handoff plan`
+   - `kse auto handoff queue`
+2. 将 handoff manifest 解析为可执行阶段计划（precheck/spec validation/execution/observability）。
+3. 将 handoff manifest 生成 close-loop-batch 目标队列（支持 dry-run、append、known-gaps 开关）。
+4. 补齐单测覆盖（plan/queue/dry-run 分支）。
+5. 更新命令参考与中英文文档入口。
+
+## 下一阶段（P1）
+
+1. 新增 `kse auto handoff run`：
+   - 一条命令串行执行 `plan -> queue -> close-loop-batch -> observability`。
+   - 支持 `--dry-run` 与失败自动中断。
+2. 新增 handoff 结果归档：
+   - 输出 `.kiro/reports/handoff-runs/<session>.json`。
+   - 汇总每个 spec 的校验状态与阻塞项。
+3. 增加 handoff 门禁策略：
+   - `--min-spec-success-rate`
+   - `--max-risk-level`
+   - `--require-ontology-validation`
+
+## 中期增强（P2）
+
+1. 将 handoff 批次映射为主从 agent 编排输入：
+   - 根据 spec 依赖自动分批并发。
+2. 引入 template 差异检测：
+   - 对比 handoff 模板与本地模板库差异。
+3. 增加跨轮次回归分析：
+   - 对比本轮与上轮 handoff 的质量、风险与收敛速度。
+
+## 长期目标（P3）
+
+1. 抽象成通用“外部项目 handoff 适配框架”（不只 331-poc）。
+2. 与 release evidence 合并，形成可发布的治理报表。
+3. 将 handoff 质量指标纳入 `kse auto governance close-loop` 的默认评估维度。

package/docs/331-poc-dual-track-integration-guide.md

@@ -0,0 +1,106 @@
+# 331-poc 双轨协同对接手册
+
+> 目的：在 `kiro-spec-engine` 侧承接 331-poc 的深度补全成果，完成模板接入、ontology 校验、主从编排与闭环验收。
+
+## 1. 输入契约（来自 331-poc）
+
+每一轮从 `E:\workspace\331-poc` 接收以下产物：
+
+1. 完成态 Spec（requirements/design/tasks + `custom/scene.yaml` + `custom/scene-package.json`）。
+2. 模板导出目录：`.kiro/templates/exports/<template-name>/`。
+3. 交接包：`docs/handoffs/handoff-manifest.json` + 证据文档。
+
+若输入不满足以上三类，KSE 侧不进入接入批次。
+
+## 2. KSE 侧接入流程
+
+## 2.0 一键化入口（推荐）
+
+先基于 handoff manifest 生成计划和队列，再执行批次：
+
+```bash
+npx kse auto handoff plan --manifest ../331-poc/docs/handoffs/handoff-manifest.json --out .kiro/reports/handoff-plan.json --json
+npx kse auto handoff queue --manifest ../331-poc/docs/handoffs/handoff-manifest.json --out .kiro/auto/handoff-goals.lines --json
+npx kse auto close-loop-batch .kiro/auto/handoff-goals.lines --format lines --batch-autonomous --continue-on-error --json
+```
+
+## 2.1 批次 1：输入预检
+
+```bash
+npx kse status --verbose
+npx kse doctor --docs
+```
+
+核对 `handoff-manifest.json`：
+1. `specs[]` 非空。
+2. `templates[]` 非空。
+3. `ontology_validation` 有最近一次执行记录。
+
+## 2.2 批次 2：scene 包验证与 ontology 回归
+
+对每个 handoff spec 执行：
+
+```bash
+npx kse scene package-validate --spec <spec-name> --spec-package custom/scene-package.json --strict --json
+npx kse scene ontology validate --package .kiro/specs/<spec-name>/custom --json
+npx kse scene ontology impact --package .kiro/specs/<spec-name>/custom --ref <ref> --max-depth 2 --json
+npx kse scene ontology path --package .kiro/specs/<spec-name>/custom --from <from-ref> --to <to-ref> --json
+```
+
+## 2.3 批次 3：模板层接入
+
+对于 scene package 模板链路（如果本轮包含 scene-package 模板）：
+
+```bash
+npx kse scene package-publish --spec <spec-name> --out-dir .kiro/templates/scene-packages --json --force
+npx kse scene package-registry --template-dir .kiro/templates/scene-packages --strict --json
+npx kse scene package-gate-template --out .kiro/templates/scene-package-gate-policy.json --profile three-layer --force --json
+npx kse scene package-gate --registry .kiro/templates/scene-packages/registry.json --policy .kiro/templates/scene-package-gate-policy.json --strict --json
+```
+
+说明：Spec 模板（`templates create-from-spec` 导出）与 scene package 模板是两条链路，可并行维护，但推荐在同一交接批次一并校验。
+
+## 2.4 批次 4：主从编排闭环验证
+
+基于本轮 spec 组合，执行自动闭环 dry-run/正式 run：
+
+```bash
+npx kse auto close-loop --specs "<spec-a>,<spec-b>,<spec-c>" --dry-run --json
+npx kse auto close-loop --specs "<spec-a>,<spec-b>,<spec-c>" --json
+npx kse auto observability snapshot --json
+```
+
+判定标准：
+1. 编排成功率满足门槛。
+2. 不出现高风险未处置项。
+3. observability 快照可追踪到本轮变更。
+
+## 3. KSE 侧当前需持续适配的点
+
+1. 对接自动化：把 331 handoff manifest 解析为可执行批次计划。
+2. ontology 深化：将“业务规则/决策逻辑”映射为可量化 gate 指标。
+3. 多 spec 主从调度：按依赖图自动分批并控制并行度。
+4. 发布治理：把 handoff 批次结果写入统一 release evidence。
+
+## 4. 角色划分
+
+1. 331-poc Agent：交付业务事实、完成态 Spec、模板和证据。
+2. KSE Agent：执行接入验证、治理门禁、主从闭环与发布收口。
+3. Master Agent：维护跨仓上下文与批次节奏。
+
+## 5. 失败处理
+
+1. 输入缺失：退回 331-poc，标注缺失项，不进入 KSE 接入。
+2. ontology 校验失败：先修 ref/lineage，再跑 gate。
+3. 主从编排失败：降并发、缩批次、保留快照后重试。
+
+## 6. 最终交付口径
+
+每个接入批次结束后，KSE 侧必须输出：
+1. 接入批次执行记录（命令、结果、失败点）。
+2. gate 与 observability 快照。
+3. 下一批次建议（可直接执行）。
+
+## 7. 持续推进参考
+
+KSE 侧后续增强计划见：`docs/331-poc-adaptation-roadmap.md`

package/docs/README.md

@@ -90,6 +90,8 @@ Detailed technical documentation:
 - **[Multi-Repository Management Guide](multi-repo-management-guide.md)** - Managing multiple Git repositories
 - **[Value Observability Guide](value-observability-guide.md)** - KPI snapshot, baseline, trend, and gate evidence workflow
 - **[Scene Runtime Guide](scene-runtime-guide.md)** - Scene template engine, quality pipeline, ontology, and Moqui ERP integration
+- **[331-poc Dual-Track Integration Guide](331-poc-dual-track-integration-guide.md)** - Handoff contract and integration playbook between 331-poc and kse
+- **[331-poc Adaptation Roadmap](331-poc-adaptation-roadmap.md)** - Ongoing KSE-side adaptation backlog and rollout phases
 - **[Multi-Agent Coordination Guide](multi-agent-coordination-guide.md)** - Multi-agent parallel coordination for concurrent development
 - **[Troubleshooting](troubleshooting.md)** - Solutions to common problems
 - **[FAQ](faq.md)** - Answers to frequently asked questions
@@ -184,6 +186,8 @@ Detailed technical documentation:
 
 ### Scene Runtime
 - [Scene Runtime Guide](scene-runtime-guide.md)
+- [331-poc Dual-Track Integration Guide](331-poc-dual-track-integration-guide.md)
+- [331-poc Adaptation Roadmap](331-poc-adaptation-roadmap.md)
 - [Scene Template Engine](command-reference.md#scene-template-engine)
 - [Scene Quality Pipeline](command-reference.md#scene-template-quality-pipeline)
 - [Scene Ontology](command-reference.md#scene-ontology-enhancement)

package/docs/command-reference.md

@@ -508,6 +508,12 @@ kse auto schema check --json
 kse auto schema migrate --json                           # dry-run by default
 kse auto schema migrate --apply --json                  # apply schema_version migration
 kse auto schema migrate --only close-loop-session,batch-session --apply --json
+
+# Dual-track handoff integration (e.g., 331-poc -> kse)
+kse auto handoff plan --manifest ../331-poc/docs/handoffs/handoff-manifest.json --json
+kse auto handoff plan --manifest ../331-poc/docs/handoffs/handoff-manifest.json --strict --out .kiro/reports/handoff-plan.json --json
+kse auto handoff queue --manifest ../331-poc/docs/handoffs/handoff-manifest.json --out .kiro/auto/handoff-goals.lines --json
+kse auto close-loop-batch .kiro/auto/handoff-goals.lines --format lines --batch-autonomous --continue-on-error --json
 ``` 
 
 DoD-related options:
@@ -738,6 +744,10 @@ Autonomous archive schema compatibility:
 - `kse auto schema migrate [--only <scopes>] [--target-version <version>] [--apply] [--json]`: migrate/backfill `schema_version` across autonomous archives.
   - Default mode is dry-run; use `--apply` to persist changes.
 
+Dual-track handoff integration:
+- `kse auto handoff plan --manifest <path> [--out <path>] [--strict] [--strict-warnings] [--json]`: parse handoff manifest (source project, specs, templates, known gaps) and generate an executable KSE integration phase plan.
+- `kse auto handoff queue --manifest <path> [--out <path>] [--append] [--no-include-known-gaps] [--dry-run] [--json]`: generate close-loop batch goal queue from handoff manifest and optionally persist line-based queue file (default `.kiro/auto/handoff-goals.lines`).
+
 Recommended `.kiro/config/orchestrator.json`:
 
 ```json

package/docs/zh/README.md

@@ -171,6 +171,18 @@
 - Ontology 图、Action Abstraction、Data Lineage、Agent Hints
 - Moqui ERP 连接、发现、模板提取
 
+### [331-poc 双轨协同对接手册](../331-poc-dual-track-integration-guide.md)
+**331-poc 与 kse 协同执行指南** - 交接契约、接入命令链、主从闭环验收
+- 331 深化成果输入约束
+- KSE 侧模板/ontology/gate 验证流程
+- 双仓协同失败回退策略
+
+### [331-poc 适配路线图](../331-poc-adaptation-roadmap.md)
+**KSE 侧持续适配清单** - 已完成、下一阶段、中期增强与长期目标
+- handoff 自动化命令演进
+- 主从编排与门禁增强
+- 跨轮次回归与发布治理集成
+
 ### [Value 可观测指南](value-observability-guide.md)
 **KPI 量化交付指南** - 快照、基线、趋势、门禁证据
 - 周度 KPI 快照生成

package/lib/commands/auto.js

@@ -12,6 +12,7 @@ const chalk = require('chalk');
 
 const AUTO_ARCHIVE_SCHEMA_VERSION = '1.0';
 const AUTO_ARCHIVE_SCHEMA_SUPPORTED_VERSIONS = new Set([AUTO_ARCHIVE_SCHEMA_VERSION]);
+const AUTO_HANDOFF_DEFAULT_QUEUE_FILE = '.kiro/auto/handoff-goals.lines';
 
 /**
  * Register auto commands
@@ -1349,6 +1350,86 @@ function registerAutoCommands(program) {
       }
     });
 
+  const autoHandoff = auto
+    .command('handoff')
+    .description('Plan and stage dual-track handoff integration workflows');
+
+  autoHandoff
+    .command('plan')
+    .description('Build an executable KSE integration plan from a handoff manifest JSON')
+    .requiredOption('--manifest <path>', 'Path to handoff-manifest.json')
+    .option('--out <path>', 'Write generated integration plan JSON to file')
+    .option('--strict', 'Fail when manifest validation contains errors')
+    .option('--strict-warnings', 'Fail when manifest validation contains warnings')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        const result = await buildAutoHandoffPlan(process.cwd(), options);
+        if (options.out) {
+          await maybeWriteOutput(result, options.out, process.cwd());
+        }
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(chalk.blue('Auto handoff integration plan:'));
+        console.log(chalk.gray(`  Manifest: ${result.manifest_path}`));
+        console.log(chalk.gray(`  Source project: ${result.source_project || 'unknown'}`));
+        console.log(chalk.gray(`  Specs: ${result.handoff.spec_count}`));
+        console.log(chalk.gray(`  Templates: ${result.handoff.template_count}`));
+        console.log(chalk.gray(`  Validation errors: ${result.validation.errors.length}`));
+        console.log(chalk.gray(`  Validation warnings: ${result.validation.warnings.length}`));
+        console.log(chalk.gray(`  Phases: ${result.phases.length}`));
+        if (result.output_file) {
+          console.log(chalk.gray(`  Output: ${result.output_file}`));
+        }
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red(`Error: ${error.message}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  autoHandoff
+    .command('queue')
+    .description('Generate close-loop queue goals from a handoff manifest JSON')
+    .requiredOption('--manifest <path>', 'Path to handoff-manifest.json')
+    .option('--out <path>', `Queue output file (default: ${AUTO_HANDOFF_DEFAULT_QUEUE_FILE})`, AUTO_HANDOFF_DEFAULT_QUEUE_FILE)
+    .option('--append', 'Append generated goals to existing queue file')
+    .option('--no-include-known-gaps', 'Exclude known_gaps entries from generated queue goals')
+    .option('--dry-run', 'Preview generated queue goals without writing file')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        const result = await buildAutoHandoffQueue(process.cwd(), options);
+        if (!result.dry_run) {
+          await writeAutoHandoffQueueFile(process.cwd(), result, options);
+        }
+        if (options.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        console.log(chalk.blue('Auto handoff queue generated:'));
+        console.log(chalk.gray(`  Manifest: ${result.manifest_path}`));
+        console.log(chalk.gray(`  Goals: ${result.goal_count}`));
+        console.log(chalk.gray(`  Include known gaps: ${result.include_known_gaps ? 'yes' : 'no'}`));
+        console.log(chalk.gray(`  Mode: ${result.dry_run ? 'dry-run' : (result.append ? 'append' : 'overwrite')}`));
+        if (result.output_file) {
+          console.log(chalk.gray(`  Queue file: ${result.output_file}`));
+        }
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red(`Error: ${error.message}`));
+        }
+        process.exit(1);
+      }
+    });
+
   const autoSchema = auto
     .command('schema')
     .description('Check and migrate autonomous archive schema compatibility');
@@ -5763,6 +5844,418 @@ async function maybeWriteTextOutput(result, content, outCandidate, projectPath)
   result.output_file = outputPath;
 }
 
+function normalizeAutoHandoffManifestPath(projectPath, manifestCandidate) {
+  const candidate = typeof manifestCandidate === 'string'
+    ? manifestCandidate.trim()
+    : '';
+  if (!candidate) {
+    throw new Error('handoff manifest path is required');
+  }
+  return path.isAbsolute(candidate)
+    ? candidate
+    : path.join(projectPath, candidate);
+}
+
+function toAutoHandoffCliPath(projectPath, absolutePath) {
+  const relative = path.relative(projectPath, absolutePath);
+  if (relative && !relative.startsWith('..') && !path.isAbsolute(relative)) {
+    return relative.split(path.sep).join('/');
+  }
+  return absolutePath;
+}
+
+function quoteCliArg(value) {
+  const raw = `${value || ''}`;
+  if (raw.length === 0) {
+    return '""';
+  }
+  if (!/[\s"'`]/.test(raw)) {
+    return raw;
+  }
+  return `"${raw.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+function normalizeHandoffText(value) {
+  if (typeof value === 'string') {
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+  }
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return `${value}`;
+  }
+  return null;
+}
+
+function readHandoffPathValue(input, keyPath) {
+  if (!input || typeof input !== 'object') {
+    return null;
+  }
+  const parts = String(keyPath || '')
+    .split('.')
+    .map(part => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) {
+    return null;
+  }
+  let cursor = input;
+  for (const part of parts) {
+    if (!cursor || typeof cursor !== 'object' || !(part in cursor)) {
+      return null;
+    }
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+
+function normalizeHandoffIdentifier(entry, fieldCandidates = []) {
+  const directText = normalizeHandoffText(entry);
+  if (directText) {
+    return directText;
+  }
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return null;
+  }
+
+  for (const field of fieldCandidates) {
+    const value = readHandoffPathValue(entry, field);
+    const normalized = normalizeHandoffText(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+
+  return null;
+}
+
+function collectUniqueIdentifiers(rawEntries, fieldCandidates, label) {
+  const warnings = [];
+  if (rawEntries === undefined || rawEntries === null) {
+    return { values: [], warnings };
+  }
+  if (!Array.isArray(rawEntries)) {
+    return {
+      values: [],
+      warnings: [`${label} must be an array`]
+    };
+  }
+
+  const values = [];
+  const seen = new Set();
+  rawEntries.forEach((entry, index) => {
+    const normalized = normalizeHandoffIdentifier(entry, fieldCandidates);
+    if (!normalized) {
+      warnings.push(`${label}[${index}] is invalid and was ignored`);
+      return;
+    }
+    if (seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    values.push(normalized);
+  });
+
+  return { values, warnings };
+}
+
+function collectKnownGaps(rawKnownGaps) {
+  const warnings = [];
+  if (rawKnownGaps === undefined || rawKnownGaps === null) {
+    return { gaps: [], warnings };
+  }
+  if (!Array.isArray(rawKnownGaps)) {
+    return {
+      gaps: [],
+      warnings: ['known_gaps must be an array']
+    };
+  }
+
+  const gaps = [];
+  rawKnownGaps.forEach((entry, index) => {
+    const normalized = normalizeHandoffIdentifier(entry, [
+      'gap',
+      'title',
+      'description',
+      'message',
+      'name',
+      'id'
+    ]);
+    if (!normalized) {
+      warnings.push(`known_gaps[${index}] is invalid and was ignored`);
+      return;
+    }
+    gaps.push(normalized);
+  });
+  return { gaps, warnings };
+}
+
+function normalizeAutoHandoffManifest(payload = {}) {
+  const validationErrors = [];
+  const validationWarnings = [];
+
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('handoff manifest must be a JSON object');
+  }
+
+  const sourceProject = normalizeHandoffText(payload.source_project);
+  if (!sourceProject) {
+    validationWarnings.push('source_project is missing');
+  }
+
+  const timestamp = normalizeHandoffText(payload.timestamp);
+  if (!timestamp) {
+    validationWarnings.push('timestamp is missing');
+  }
+
+  const specsCollected = collectUniqueIdentifiers(
+    payload.specs,
+    ['name', 'spec', 'spec_name', 'spec_id', 'id', 'spec.name', 'spec.id'],
+    'specs'
+  );
+  validationWarnings.push(...specsCollected.warnings);
+  if (specsCollected.values.length === 0) {
+    validationErrors.push('specs must include at least one valid spec identifier');
+  }
+
+  const templatesCollected = collectUniqueIdentifiers(
+    payload.templates,
+    ['name', 'template', 'template_name', 'id', 'template.id', 'template.name'],
+    'templates'
+  );
+  validationWarnings.push(...templatesCollected.warnings);
+  if (templatesCollected.values.length === 0) {
+    validationWarnings.push('templates is empty');
+  }
+
+  const knownGapCollected = collectKnownGaps(payload.known_gaps);
+  validationWarnings.push(...knownGapCollected.warnings);
+
+  const ontologyValidation = payload.ontology_validation && typeof payload.ontology_validation === 'object'
+    ? payload.ontology_validation
+    : null;
+  if (!ontologyValidation) {
+    validationWarnings.push('ontology_validation is missing');
+  }
+
+  const nextBatch = payload.next_batch && typeof payload.next_batch === 'object'
+    ? payload.next_batch
+    : null;
+
+  return {
+    source_project: sourceProject,
+    timestamp,
+    specs: specsCollected.values,
+    templates: templatesCollected.values,
+    known_gaps: knownGapCollected.gaps,
+    ontology_validation: ontologyValidation,
+    next_batch: nextBatch,
+    validation: {
+      errors: validationErrors,
+      warnings: validationWarnings
+    }
+  };
+}
+
+async function loadAutoHandoffManifest(projectPath, manifestCandidate) {
+  const manifestPath = normalizeAutoHandoffManifestPath(projectPath, manifestCandidate);
+  if (!await fs.pathExists(manifestPath)) {
+    throw new Error(`handoff manifest not found: ${manifestPath}`);
+  }
+
+  let payload;
+  try {
+    payload = await fs.readJson(manifestPath);
+  } catch (error) {
+    throw new Error(`invalid handoff manifest JSON: ${manifestPath} (${error.message})`);
+  }
+
+  const normalized = normalizeAutoHandoffManifest(payload);
+  return {
+    manifest_path: manifestPath,
+    manifest_file: toAutoHandoffCliPath(projectPath, manifestPath),
+    ...normalized
+  };
+}
+
+function buildAutoHandoffPhaseCommands(projectPath, manifestPath, specs = []) {
+  const manifestCli = quoteCliArg(toAutoHandoffCliPath(projectPath, manifestPath));
+  const phases = [];
+
+  phases.push({
+    id: 'precheck',
+    title: 'Precheck',
+    goal: 'Validate handoff manifest integrity and repository readiness',
+    commands: [
+      `kse auto handoff plan --manifest ${manifestCli} --json`,
+      'kse auto governance stats --json'
+    ]
+  });
+
+  const specCommands = [];
+  for (const specName of specs) {
+    const specArg = quoteCliArg(specName);
+    const specPackagePath = quoteCliArg(`.kiro/specs/${specName}/custom`);
+    specCommands.push(`kse auto spec status ${specArg} --json`);
+    specCommands.push(`kse auto spec instructions ${specArg} --json`);
+    specCommands.push(`kse scene package-validate --spec ${specArg} --spec-package custom/scene-package.json --strict --json`);
+    specCommands.push(`kse scene ontology validate --package ${specPackagePath} --json`);
+  }
+  phases.push({
+    id: 'spec-validation',
+    title: 'Spec Validation',
+    goal: 'Validate spec docs, tasks, scene package contract, and ontology consistency',
+    commands: specCommands
+  });
+
+  const queueCli = quoteCliArg(AUTO_HANDOFF_DEFAULT_QUEUE_FILE);
+  phases.push({
+    id: 'execution',
+    title: 'Autonomous Execution',
+    goal: 'Generate queue goals and run autonomous close-loop batch integration',
+    commands: [
+      `kse auto handoff queue --manifest ${manifestCli} --out ${queueCli} --json`,
+      `kse auto close-loop-batch ${queueCli} --format lines --batch-autonomous --continue-on-error --json`
+    ]
+  });
+
+  phases.push({
+    id: 'observability',
+    title: 'Observability and Governance',
+    goal: 'Snapshot integration evidence and plan remaining governance actions',
+    commands: [
+      'kse auto observability snapshot --json',
+      'kse auto governance maintain --session-keep 50 --batch-session-keep 50 --controller-session-keep 50 --json'
+    ]
+  });
+
+  return phases;
+}
+
+async function buildAutoHandoffPlan(projectPath, options = {}) {
+  const handoff = await loadAutoHandoffManifest(projectPath, options.manifest);
+  const validationErrors = Array.isArray(handoff.validation.errors) ? handoff.validation.errors : [];
+  const validationWarnings = Array.isArray(handoff.validation.warnings) ? handoff.validation.warnings : [];
+
+  if (options.strict && validationErrors.length > 0) {
+    throw new Error(`handoff plan validation failed: ${validationErrors.join('; ')}`);
+  }
+  if (options.strictWarnings && validationWarnings.length > 0) {
+    throw new Error(`handoff plan validation warnings: ${validationWarnings.join('; ')}`);
+  }
+
+  const phases = buildAutoHandoffPhaseCommands(projectPath, handoff.manifest_path, handoff.specs);
+  return {
+    mode: 'auto-handoff-plan',
+    generated_at: new Date().toISOString(),
+    manifest_path: handoff.manifest_path,
+    source_project: handoff.source_project,
+    handoff: {
+      timestamp: handoff.timestamp,
+      spec_count: handoff.specs.length,
+      template_count: handoff.templates.length,
+      known_gap_count: handoff.known_gaps.length,
+      specs: handoff.specs,
+      templates: handoff.templates,
+      known_gaps: handoff.known_gaps,
+      ontology_validation: handoff.ontology_validation,
+      next_batch: handoff.next_batch
+    },
+    validation: {
+      is_valid: validationErrors.length === 0,
+      errors: validationErrors,
+      warnings: validationWarnings
+    },
+    phases,
+    recommendations: [
+      `kse auto handoff queue --manifest ${quoteCliArg(handoff.manifest_file)} --out ${quoteCliArg(AUTO_HANDOFF_DEFAULT_QUEUE_FILE)} --json`,
+      `kse auto close-loop-batch ${quoteCliArg(AUTO_HANDOFF_DEFAULT_QUEUE_FILE)} --format lines --batch-autonomous --continue-on-error --json`
+    ]
+  };
+}
+
+function buildAutoHandoffQueueGoals(handoff, options = {}) {
+  const includeKnownGaps = options.includeKnownGaps !== false;
+  const goals = [];
+  const seen = new Set();
+  const pushGoal = value => {
+    const normalized = normalizeHandoffText(value);
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    goals.push(normalized);
+  };
+
+  for (const specName of handoff.specs) {
+    pushGoal(`integrate handoff spec ${specName} with scene package validation, ontology consistency checks, and close-loop completion`);
+  }
+
+  for (const templateName of handoff.templates) {
+    pushGoal(`validate handoff template ${templateName} for template registry compatibility and release readiness`);
+  }
+
+  if (includeKnownGaps) {
+    for (const gap of handoff.known_gaps) {
+      pushGoal(`remediate handoff known gap: ${gap}`);
+    }
+  }
+
+  pushGoal('generate unified observability snapshot and governance follow-up recommendations for this handoff batch');
+  return goals;
+}
+
+async function buildAutoHandoffQueue(projectPath, options = {}) {
+  const handoff = await loadAutoHandoffManifest(projectPath, options.manifest);
+  const validationErrors = Array.isArray(handoff.validation.errors) ? handoff.validation.errors : [];
+  if (validationErrors.length > 0) {
+    throw new Error(`handoff queue validation failed: ${validationErrors.join('; ')}`);
+  }
+
+  const includeKnownGaps = options.includeKnownGaps !== false;
+  const goals = buildAutoHandoffQueueGoals(handoff, { includeKnownGaps });
+  if (goals.length === 0) {
+    throw new Error('handoff queue produced no goals');
+  }
+
+  return {
+    mode: 'auto-handoff-queue',
+    generated_at: new Date().toISOString(),
+    manifest_path: handoff.manifest_path,
+    dry_run: Boolean(options.dryRun),
+    append: Boolean(options.append),
+    include_known_gaps: includeKnownGaps,
+    goal_count: goals.length,
+    goals,
+    validation: {
+      errors: handoff.validation.errors,
+      warnings: handoff.validation.warnings
+    },
+    recommendations: [
+      `kse auto close-loop-batch ${quoteCliArg(options.out || AUTO_HANDOFF_DEFAULT_QUEUE_FILE)} --format lines --batch-autonomous --continue-on-error --json`
+    ]
+  };
+}
+
+async function writeAutoHandoffQueueFile(projectPath, queueResult, options = {}) {
+  const outCandidate = typeof options.out === 'string' && options.out.trim().length > 0
+    ? options.out.trim()
+    : AUTO_HANDOFF_DEFAULT_QUEUE_FILE;
+  const outputPath = path.isAbsolute(outCandidate)
+    ? outCandidate
+    : path.join(projectPath, outCandidate);
+  await fs.ensureDir(path.dirname(outputPath));
+
+  const content = `${queueResult.goals.join('\n')}\n`;
+  if (options.append && await fs.pathExists(outputPath)) {
+    const existing = await fs.readFile(outputPath, 'utf8');
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    await fs.appendFile(outputPath, `${separator}${content}`, 'utf8');
+  } else {
+    await fs.writeFile(outputPath, content, 'utf8');
+  }
+
+  queueResult.output_file = outputPath;
+}
+
 function buildProgramKpiSnapshot(summary) {
   const results = Array.isArray(summary && summary.results) ? summary.results : [];
   const totalGoals = Number(summary && summary.total_goals) || results.length || 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.47.6",
+  "version": "1.47.7",
   "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": {