kiro-spec-engine 1.47.5 → 1.47.7

package/CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **Scene ontology impact/path analysis commands**: Added `kse scene ontology impact` (reverse dependency blast-radius analysis with `--relation` and `--max-depth`) and `kse scene ontology path` (shortest relation path between refs with optional `--undirected`) to improve ontology-driven change planning and explainability.
+- **Close-loop quantitative DoD gates**: Added `--dod-max-risk-level`, `--dod-kpi-min-completion-rate`, `--dod-max-success-rate-drop`, and `--dod-baseline-window` so autonomous closure can enforce explicit risk/KPI/baseline thresholds beyond binary checks.
+- **Close-loop conflict/ontology execution planning**: Added lease-conflict scheduling governance and scene ontology scheduling guidance with opt-out controls (`--no-conflict-governance`, `--no-ontology-guidance`), and surfaced planning telemetry in `portfolio.execution_plan` plus agent sync plan output.
+- **Close-loop strategy memory feedback loop**: Added persisted strategy memory (`.kiro/auto/close-loop-strategy-memory.json`) to reuse prior goal-level policy hints and track-level feedback bias during decomposition, with run telemetry under `strategy_memory`.
+- **Unified autonomous observability snapshot**: Added `kse auto observability snapshot` to aggregate close-loop, batch, controller, governance, and KPI-trend telemetry into one machine-readable payload.
+- **Agent-facing spec JSON interfaces**: Added `kse auto spec status <spec-name> --json` and `kse auto spec instructions <spec-name> --json` for structured status/instruction retrieval in master-sub agent workflows.
+- **Autonomous archive schema compatibility tooling**: Added `kse auto schema check` and `kse auto schema migrate` (dry-run by default, `--apply` to persist) to audit and migrate `schema_version` across autonomous archives.
 - **Governance resumed-session filtering and ratio telemetry**: `kse auto governance session list|stats` now support `--resume-only`, with new resumed/fresh counters and resume lineage composition telemetry (`resumed_rate_percent`, `resumed_from_counts`) for resumed-chain observability.
 - **Governance close-loop post-run retention hook**: Added `--governance-session-keep` and `--governance-session-older-than-days` to `kse auto governance close-loop` for automatic governance session archive pruning after each run, with current session protection and telemetry in `governance_session_prune`.
 - **Governance resume drift guardrails**: `kse auto governance close-loop --governance-resume` now reuses persisted target/advisory policy defaults by default and blocks explicit policy drift unless `--governance-resume-allow-drift` is set, reducing accidental resume misconfiguration.

package/README.md

@@ -537,6 +537,11 @@ kse auto close-loop-controller .kiro/auto/program-queue.lines --wait-on-empty --
 kse auto close-loop-controller --controller-resume latest --json # Resume autonomous controller from latest persisted checkpoint
 kse auto controller-session list --limit 50 --json # Inspect persisted close-loop-controller summary sessions
 kse auto controller-session prune --keep 20 --older-than-days 14 --dry-run --json # Prune old controller summaries by retention policy
+kse auto observability snapshot --days 14 --json # Unified autonomous observability snapshot (sessions + governance + trend)
+kse auto spec status 121-00-master --json # Agent-facing structured spec status interface
+kse auto spec instructions 121-02-sub-track --json # Agent-facing execution instructions for one spec
+kse auto schema check --json # Check autonomous archive schema compatibility
+kse auto schema migrate --apply --json # Backfill/migrate schema_version for autonomous archives
 
 # Spec workflow (recommended)
 kse spec bootstrap --name <spec> --non-interactive         # Generate requirements/design/tasks draft

package/README.zh.md

@@ -454,6 +454,11 @@ kse auto close-loop-controller .kiro/auto/program-queue.lines --wait-on-empty --
 kse auto close-loop-controller --controller-resume latest --json # 从最近一次 controller 检查点恢复自治推进
 kse auto controller-session list --limit 50 --json # 查看持久化 close-loop-controller 摘要会话
 kse auto controller-session prune --keep 20 --older-than-days 14 --dry-run --json # 按保留策略清理旧 controller 摘要
+kse auto observability snapshot --days 14 --json # 统一自治可观测快照（会话 + 治理 + 趋势）
+kse auto spec status 121-00-master --json # 面向 Agent 的结构化 Spec 状态接口
+kse auto spec instructions 121-02-sub-track --json # 面向 Agent 的 Spec 执行指令接口
+kse auto schema check --json # 检查自治归档 schema 兼容性
+kse auto schema migrate --apply --json # 回填/迁移自治归档 schema_version
 
 # Spec 工作流（推荐）
 kse spec bootstrap --name <spec> --non-interactive          # 生成 requirements/design/tasks 初稿

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

@@ -494,11 +494,35 @@ kse auto recovery-memory clear --json
 # Autonomous KPI trend (weekly/daily buckets + CSV export)
 kse auto kpi trend --weeks 12 --period week --mode all --json
 kse auto kpi trend --weeks 8 --period day --mode program --csv --out ./auto-kpi-trend.csv
+
+# Unified observability snapshot (sessions + governance + KPI trend)
+kse auto observability snapshot --days 14 --status completed,failed --json
+kse auto observability snapshot --out .kiro/reports/auto-observability.json --json
+
+# Agent-facing spec interfaces
+kse auto spec status 121-00-master --json
+kse auto spec instructions 121-02-sub-track --json
+
+# Autonomous archive schema compatibility
+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:
 - `--dod-tests <command>`: run a final shell command as a completion gate
 - `--dod-tests-timeout <ms>`: timeout for `--dod-tests` (default `600000`)
+- `--dod-max-risk-level <low|medium|high>`: fail DoD when derived run risk is above threshold
+- `--dod-kpi-min-completion-rate <n>`: minimum close-loop completion rate percent (`0-100`)
+- `--dod-max-success-rate-drop <n>`: max allowed completion-rate drop vs recent baseline (`0-100`)
+- `--dod-baseline-window <n>`: number of recent sessions used for baseline comparison (`1-50`, default `5`)
 - `--dod-tasks-closed`: require no unchecked `- [ ]` items in generated `tasks.md`
 - `--no-dod-docs`: skip doc completeness gate
 - `--no-dod-collab`: skip collaboration completion gate
@@ -515,6 +539,8 @@ DoD-related options:
 - `--replan-attempts <n>`: max automatic replan cycles after failed orchestration (`0-5`, default `1`)
 - `--replan-no-progress-window <n>`: stop replan when no progress repeats for `n` failed cycles (`1-10`, default `3`)
 - `--no-replan`: disable automatic replan cycle
+- `--no-conflict-governance`: disable lease-conflict prediction and scheduling guard
+- `--no-ontology-guidance`: disable scene ontology `agent_hints` scheduling guidance
 
 Close-loop batch (`kse auto close-loop-batch <goals-file>`) options:
 - supports shared close-loop execution options (for example: `--subs`, `--max-parallel`, `--dod*`, `--replan*`, `--dry-run`, `--json`)
@@ -705,6 +731,23 @@ Autonomous KPI trend:
   - `--csv` prints CSV rows to stdout and writes CSV when used with `--out` (JSON remains default).
   - JSON output includes `mode_breakdown` (batch/program/recover/controller/other run distribution), `anomaly_detection`, and flattened `anomalies` (latest-period regression checks against historical baseline).
 
+Unified observability snapshot:
+- `kse auto observability snapshot [--days <n>] [--status <csv>] [--weeks <n>] [--trend-mode <mode>] [--trend-period <period>] [--out <path>] [--json]`: generate one unified observability snapshot that combines close-loop session stats, batch stats, controller stats, governance session stats, governance health, and KPI trend.
+- JSON output includes top-level `highlights` plus detailed archive/trend payloads under `snapshots`.
+
+Agent-facing spec interfaces:
+- `kse auto spec status <spec-name> [--json]`: structured status for one spec (`docs`, `task_progress`, `collaboration`, `health`).
+- `kse auto spec instructions <spec-name> [--json]`: machine-readable execution instructions for one spec (`next_actions`, `priority_open_tasks`, recommended commands, document excerpts).
+
+Autonomous archive schema compatibility:
+- `kse auto schema check [--only <scopes>] [--json]`: scan archive schema compatibility (`schema_version`) for `close-loop-session`, `batch-session`, `controller-session`, and `governance-session`.
+- `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 快照生成