kiro-spec-engine 1.46.2 → 1.47.0

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **KPI sample generator command**: Added `kse value metrics sample` to generate a ready-to-use KPI input JSON scaffold (`kpi-input.json`) for first-time observability runs.
+- **Value observability documentation track**: Added dedicated EN/ZH guides for KPI snapshot/baseline/trend workflow (`docs/value-observability-guide.md`, `docs/zh/value-observability-guide.md`) and wired entry links from README + docs indexes for faster discovery of measurable delivery capabilities.
+- **Release communication assets**: Added bilingual v1.46.2 release notes (`docs/releases/v1.46.2.md`, `docs/zh/releases/v1.46.2.md`) and a reusable pre-release checklist (`docs/release-checklist.md`).
+- **Release validation artifacts**: Added release-readiness evidence reports in EN/ZH (`docs/releases/v1.46.2-validation.md`, `docs/zh/releases/v1.46.2-validation.md`) with test and package dry-run results.
+- **Release archive indexes**: Added release archive index pages (`docs/releases/README.md`, `docs/zh/releases/README.md`) and wired links from documentation indexes for faster release artifact discovery.
+- **Value metrics helper test coverage**: Added deterministic tests for ISO week period derivation and sample payload structure in command-level unit tests.
+- **Spec 115 quality hardening program**: Added a master/sub-spec collaboration portfolio (`115-00` + `115-01..115-04`) to parallelize CI trust, Jest open-handle governance, watch follow completion, and doc link canonicalization.
+- **Test governance scripts**: Added `test:smoke`, `test:full`, `test:handles`, `test:skip-audit`, plus `scripts/check-skip-allowlist.js` and `tests/skip-allowlist.txt` for skip-test regression guardrails.
+- **Autonomous close-loop command**: Added `kse auto close-loop "<goal>"` to perform one-command goal decomposition (master/sub specs), collaboration bootstrap, and orchestration until terminal state.
+- **Definition-of-Done gates for close-loop**: Added configurable completion gates for `kse auto close-loop` (`--dod-tests`, `--dod-tasks-closed`, `--no-dod*`) so autonomous runs only report success when required evidence checks pass.
+- **DoD evidence archive for close-loop**: Added automatic DoD report persistence to `.kiro/specs/<master>/custom/dod-report.json` with CLI controls (`--dod-report`, `--no-dod-report`) for audit-ready closure evidence.
+- **Close-loop session resume**: Added session snapshot persistence for `kse auto close-loop` (`.kiro/auto/close-loop-sessions`) plus resume controls (`--resume`, `--session-id`, `--no-session`) to continue interrupted master/sub executions.
+- **Close-loop session hygiene commands**: Added `kse auto session list` and `kse auto session prune` (retention + age filters + dry-run/json) so long-running autonomous programs can maintain session archives without manual file cleanup.
+- **Spec directory retention commands**: Added `kse auto spec-session list|prune` (retention + age filters + dry-run/json) to control `.kiro/specs` growth for continuous autonomous runs.
+- **Active spec protection in retention prune**: `kse auto spec-session prune` now protects active/recently referenced specs by default (`--no-protect-active` to override).
+- **Automatic spec retention policy for program/batch/recover**: Added `--spec-session-keep` / `--spec-session-older-than-days` (`--no-spec-session-protect-active` optional) so autonomous multi-goal runs can auto-prune `.kiro/specs` after execution.
+- **Configurable spec protection window**: Added `--spec-session-protect-window-days` (and `spec-session prune --protect-window-days`) so teams can tune recent-reference protection horizon for retention safety.
+- **Spec protection reason observability**: `spec-session prune` now emits `protection_ranking_top` by default and supports `--show-protection-reasons` for per-spec reason detail (`protected_specs[*].reasons`, `protection_ranking`) during retention audits.
+- **Spec directory budget guardrail**: Added `--spec-session-max-total` with optional `--spec-session-budget-hard-fail` for batch/program/recover flows, including `spec_session_budget` telemetry in summaries to prevent uncontrolled `.kiro/specs` growth.
+- **Unified program budget gate**: Added `--program-max-elapsed-minutes`, `--program-max-agent-budget`, and `--program-max-total-sub-specs` so `close-loop-program` convergence gate can enforce time/concurrency/sub-spec budgets together with success/risk policy.
+- **Program/recover gate policy parity + auto-remediation hooks**: `close-loop-recover` now supports the same gate/fallback/budget policy flags as program mode and can emit `program_gate_auto_remediation` (auto patch/prune hints) when gate/budget checks fail.
+- **Spec growth/duplicate guardrails**: Added `--spec-session-max-created`, `--spec-session-max-created-per-goal`, and `--spec-session-max-duplicate-goals` (with hard-fail option) plus summary telemetry (`goal_input_guard`, `spec_session_growth_guard`) to reduce runaway autonomous portfolio expansion.
+- **Autonomous KPI trend command**: Added `kse auto kpi trend` to aggregate weekly success/completion, failure, sub-spec, and spec-growth telemetry from persisted autonomous summary sessions.
+- **Autonomous KPI trend period/csv/anomaly enhancement**: Extended `kse auto kpi trend` with `--period week|day`, `--csv` export mode, and JSON anomaly diagnostics (`anomaly_detection`, `anomalies`) for latest-period regression checks.
+- **Close-loop multi-goal batch command**: Added `kse auto close-loop-batch <goals-file>` with file-format autodetect (`json|lines`), `--continue-on-error`, and per-goal summary output so autonomous master/sub execution can scale across multiple goals in one run.
+- **Close-loop batch global scheduler**: Added `--batch-parallel` (`1-20`) to execute multiple goals concurrently in `close-loop-batch`, enabling master/sub portfolios to progress in parallel without manual orchestration handoffs.
+- **Close-loop batch resume from summary**: Added `--resume-from-summary <path>` to recover pending goals from a prior batch run and continue autonomous delivery without rebuilding the entire goal queue manually.
+- **Close-loop batch resume strategy selector**: Added `--resume-strategy pending|failed-only` so operators can choose whether summary resume should include unprocessed goals (`pending`) or only failed/error goals (`failed-only`).
+- **Close-loop batch global agent budget**: Added `--batch-agent-budget` and `resource_plan` output so multi-goal autonomous runs can enforce a shared concurrency budget with automatic per-goal `maxParallel` throttling.
+- **Close-loop batch complexity-weighted scheduler**: Added weighted slot scheduling (`goal_weight`/`scheduling_weight`) under batch budget mode so higher-complexity goals consume more shared budget and automatically lower same-batch concurrency.
+- **Close-loop batch priority + aging scheduler controls**: Added `--batch-priority` (`fifo|complex-first|complex-last`) and `--batch-aging-factor` (`0-100`) with `resource_plan` wait/starvation telemetry so autonomous multi-goal runs can tune ordering and fairness without manual intervention.
+- **Close-loop batch program decomposition mode**: Added `--decompose-goal` + `--program-goals` so one broad goal can be auto-split into multiple batch goals and executed as a master batch without manually authoring a goals file.
+- **Close-loop batch automatic retry rounds**: Added `--batch-retry-rounds` + `--batch-retry-strategy` (`adaptive|strict`) with `batch_retry` summary telemetry so failed/stopped goals can be retried in the same autonomous batch run without manual re-invocation.
+- **Close-loop batch session archive + latest resume**: Added automatic batch summary session persistence (`.kiro/auto/close-loop-batch-summaries`) with controls (`--batch-session-id`, `--batch-session-keep`, `--no-batch-session`) and support for `--resume-from-summary latest`.
+- **Close-loop batch session maintenance commands**: Added `kse auto batch-session list` / `kse auto batch-session prune` plus age-based retention control (`--batch-session-older-than-days`) for persisted batch summary archives.
+- **Close-loop batch until-complete retry mode**: Added `--batch-retry-until-complete` + `--batch-retry-max-rounds` so multi-goal runs can auto-drain failed/stopped goals to completion within one command invocation under bounded retry policy.
+- **Close-loop batch autonomous policy mode**: Added `--batch-autonomous` to apply closed-loop defaults automatically (continue-on-error, adaptive parallelism, complexity-first scheduling, aging boost, retry-until-complete) for hands-off program execution.
+- **Close-loop program command**: Added `kse auto close-loop-program "<goal>"` to auto-decompose one broad objective into multi-goal autonomous execution (master/sub portfolios) with closed-loop batch policy enabled by default.
+- **Close-loop program KPI snapshot**: Added `program_kpi` in `close-loop-program` summary plus `--program-kpi-out` for standalone KPI export (convergence state, risk level, retry recovery, complexity/wait profile).
+- **Close-loop program convergence gate + audit output**: Added policy gates (`--program-min-success-rate`, `--program-max-risk-level`) plus `--program-audit-out` for governance-grade audit JSON; program exits non-zero when gate policy is not met.
+- **Close-loop program gate profiles**: Added `--program-gate-profile` (`default|dev|staging|prod`) so teams can switch convergence policy baselines by environment while still allowing explicit threshold overrides.
+- **Close-loop program gate fallback tier**: Added `--program-gate-fallback-profile` (`none|default|dev|staging|prod`) so gate evaluation can use a controlled fallback policy tier when the primary gate fails.
+- **Close-loop program gate fallback chain**: Added `--program-gate-fallback-chain <profiles>` so gate evaluation can try multiple fallback policy profiles in order after primary gate failure.
+- **Close-loop program recovery time budget**: Added `--program-recover-max-minutes` so built-in auto recovery loops can stop on elapsed-time limits, with `recovery_cycle` budget telemetry.
+- **Close-loop program remediation diagnostics**: Added `program_diagnostics` (`failure_clusters` + prioritized `remediation_actions`) to turn program KPI output into actionable convergence guidance.
+- **Close-loop recovery command**: Added `kse auto close-loop-recover [summary]` with remediation-action selection (`--use-action`) to automatically replay unresolved goals using strategy patches derived from diagnostics.
+- **Close-loop recovery self-healing rounds**: Added `--recover-until-complete` + `--recover-max-rounds` with `recovery_cycle` history so recovery can run multiple rounds autonomously until convergence or bounded exhaustion.
+- **Close-loop recovery time/memory governance**: Added `--recover-max-minutes` and `--recovery-memory-ttl-days` so recovery loops can enforce elapsed-time budgets and stale-memory pruning during action selection.
+- **Recovery memory lifecycle commands**: Added `kse auto recovery-memory show|prune|clear` to inspect, prune, and reset persisted recovery strategy memory.
+- **Recovery memory scope analytics command**: Added `kse auto recovery-memory scopes` to inspect aggregate recovery-memory statistics grouped by scope.
+- **Criticality-priority scheduler mode**: Added `--batch-priority critical-first` with per-goal criticality telemetry in `resource_plan` and result summaries.
+- **Goal decomposition quality diagnostics**: Added `generated_from_goal.quality` (score, coverage ratio, warnings) for program/batch semantic decomposition observability.
+- **Goal decomposition quality auto-refinement**: Added `--program-min-quality-score` with automatic second-pass goal refinement and `quality.refinement` telemetry, so weak decompositions are improved before execution.
+- **Goal decomposition hard quality gate**: Added `--program-quality-gate` to fail execution when final decomposition quality remains below threshold after refinement.
+- **Recovery memory scope isolation + explainability**: Added `--recovery-memory-scope` and selection explanation metadata (`selection_explain`) so remediation memory can be isolated by scope and action selection is auditable.
+- **Scoped recovery memory maintenance**: `kse auto recovery-memory show|prune` now support `--scope <scope>` for targeted inspection and cleanup.
+- **Program gate fallback observability**: Program outputs now include `program_gate_fallbacks` and `program_gate_effective` fields for full fallback decision traceability.
+- **Program-level auto recovery loop**: `kse auto close-loop-program` now auto-enters bounded recovery rounds by default (`--program-recover-max-rounds`, `--no-program-auto-recover`) so one command can drive program execution to closure without manual follow-up.
+- **Recovery strategy memory**: Added persisted recovery memory (`.kiro/auto/close-loop-recovery-memory.json`) so `close-loop-recover` and program auto-recovery can reuse previously successful remediation actions when `--use-action` is omitted.
+- **Program coordination telemetry**: Added `program_coordination` output (master/sub topology, unresolved goals, scheduler snapshot) for multi-spec orchestration observability in both program and recover summaries.
+- **Close-loop batch KPI summary**: Added aggregate `metrics` in batch output (success rate, status breakdown, average sub-spec count, average replan cycles) for portfolio-level observability.
+- **Close-loop auto session retention policy**: Added `--session-keep` and `--session-older-than-days` to `kse auto close-loop` so each autonomous run can prune stale session snapshots automatically.
+- **Automatic replan loop for close-loop failures**: Added remediation replan cycles (`--replan-attempts`, `--no-replan`) so failed orchestration runs can auto-generate recovery specs and retry autonomously.
+- **Replan stall guard**: Added failed-spec signature deduplication so close-loop auto-replan stops early when the same failure set repeats, preventing low-value remediation loops.
+- **Replan no-progress stall guard**: Added `--replan-no-progress-window` so close-loop retries terminate when consecutive failed cycles show no net progress, improving autonomous convergence and reducing retry noise.
+- **Goal decomposition engine**: Added heuristic portfolio planner for automatic sub-spec splitting, dependency wiring, and deterministic spec prefix allocation.
+- **Complex-goal auto-split scaling**: Enhanced decomposition heuristic to auto-escalate sub-spec count up to 5 for high-complexity goals, strengthening master/sub parallel delivery for larger feature sets.
+- **Autonomous close-loop tests**: Added unit coverage for decomposition strategy and close-loop runner behavior (plan-only and execution paths).
+- **Autonomous CLI end-to-end regression**: Added integration coverage for `kse auto close-loop --resume latest`, `kse auto close-loop-batch --dry-run --json`, and `kse auto session list/prune` via real `bin/kiro-spec-engine.js` execution.
+- **Program gate fallback-chain integration fixture**: Added deterministic non-dry-run CLI integration coverage for primary-gate failure + fallback-chain acceptance to harden convergence policy regression checks.
+- **Spec 116 autonomous-closure portfolio**: Added `116-00` master with `116-01..116-03` sub-specs as a live master/sub example generated through the close-loop workflow, including `custom/agent-sync-plan.md`.
+- **Spec 117 autonomous hardening portfolio**: Added `117-00` master with `117-01..117-04` sub-specs to continue parallel delivery on no-confirmation closed-loop execution, master/sub decomposition, orchestration runtime, and observability gates.
+- **Spec 118 resilience/replan portfolio**: Added `118-00` master with `118-01..118-04` sub-specs for interrupted-session resume and dynamic master/sub dependency replanning hardening.
+- **Spec 119 dynamic-replanning portfolio**: Added `119-00` master with `119-01..119-04` sub-specs to drive remediation-spec generation and autonomous continuation after orchestration failures.
+- **Spec 120 replan-governance portfolio**: Added `120-00` master with `120-01..120-04` sub-specs to enforce adaptive replan policy, remediation spec governance, and autonomous convergence hardening.
+- **Semantic decomposition engine**: Added clause/category analysis (`semantic-decomposer`) and integrated it into portfolio planning for mixed-language goals.
+- **Live orchestration status streaming**: Added event/interval-driven status persistence callback support in `runOrchestration()` and wired `auto close-loop` live progress output (`--no-stream` to disable).
+
+### Changed
+- **Positioning and onboarding messaging**: Strengthened EN/ZH README and quick-start docs with explicit kse advantage matrix, 90-second value proof, and KPI observability positioning to improve first-contact clarity.
+- **CLI first-screen positioning text**: Updated `kse --help` top description in EN/ZH locales to reflect current core strengths: Spec workflow, orchestration, and KPI observability.
+- **Offline onboarding consistency**: Refreshed `START_HERE.txt`, `INSTALL_OFFLINE.txt`, and `docs/OFFLINE_INSTALL.md` to v1.46.2 guidance and aligned quick-start prerequisites with current runtime requirement (Node.js >= 16).
+- **Value metrics operator guidance**: Enhanced snapshot/baseline/trend failure messages with actionable follow-up commands (including `kse value metrics sample`) to reduce first-run friction.
+- **Top-level release navigation**: Updated EN/ZH root READMEs to expose release archive and validation report links directly from Advanced Topics for faster proof-of-value discovery.
+- **Observability guide usability**: Added EN/ZH expected JSON output examples for `snapshot --json` and `trend --json` to speed up first-run verification and integration scripting.
+- **Watch log operator flow**: Implemented `kse watch logs --follow` streaming behavior and documented follow examples in command reference.
+- **Canonical documentation links**: Standardized mixed repository links to `https://github.com/heguangyong/kiro-spec-engine` and wired canonical-link scan commands into EN/ZH release checklists.
+- **Autonomy positioning clarity**: Strengthened EN/ZH docs and command reference to emphasize closed-loop delivery and automatic master/sub spec decomposition as kse core strengths.
+- **Autonomous operator UX**: Expanded docs with semantic decomposition and live stream behavior for close-loop command usage.
+
+### Fixed
+- **npm package hygiene**: Excluded transient Python bytecode artifacts (`__pycache__`, `*.pyc/pyo/pyd`) from published package contents to reduce package noise and size.
+- **Documentation contact placeholders**: Replaced `yourusername` placeholder repository links in onboarding docs with the canonical project URL and removed stale example email contact.
+- **Jest force-exit dependency**: Removed `forceExit` from `jest.config.js` and `jest.config.ci.js`; test scripts now complete without explicit force-exit configuration.
+- **Agent termination timer leak**: `AgentSpawner._terminateProcess()` now clears both SIGKILL and safety timers on process close/settle, preventing lingering timer handles after `kill()`/`killAll()`.
+- **Validation python-check timer leak**: `checkPythonVersion()` now clears and `unref()`s its timeout with single-settle semantics, preventing post-test open-handle warnings.
+- **Orchestrator/unit test stability**: Reduced timer-based flakiness in orchestration property tests and aligned orchestrator integration defaults to avoid long-lived test timers.
+- **Recovery loop action stability**: `close-loop-recover --recover-until-complete` now pins the selected remediation action from round 1, avoiding later-round `--use-action` out-of-range aborts when diagnostics action counts change.
+- **Summary-derived goal recovery robustness**: Recovery now skips synthetic `goals_file` placeholders (for example `"(derived-from-summary)"`) when rebuilding pending goals, preventing false "goals file not found" failures in multi-round loops.
+- **Program gate dry-run correctness**: `close-loop-program` convergence gate now derives success rate from program KPI completion rate (with fallback), preventing false gate failures in dry-run program executions.
+
 ## [1.46.2] - 2026-02-14
 
 ### Added

package/README.md

@@ -48,6 +48,36 @@ graph LR
 - ✅ Anyone building features that need clear requirements and design
 - ✅ Projects that benefit from spec-driven development
 
+## Why kse Wins in AI Delivery
+
+| Advantage | kse Capability | Practical Impact |
+| --- | --- | --- |
+| Structure-first execution | Requirements → Design → Tasks + gate checks | Lower rework and fewer requirement drifts |
+| Autonomous close-loop delivery | One-command close loop (`auto close-loop`) | No step-by-step confirmation waits |
+| Multi-agent scale-out | DAG orchestration (`orchestrate run/status/stop`) | Parallel delivery without manual terminal juggling |
+| Auto portfolio decomposition | Master/Sub spec split + dependency wiring | Complex goals become executable parallel plans automatically |
+| Program self-healing closure | `auto close-loop-program` auto recovery + learned remediation memory | Failed/partial runs continue autonomously until bounded convergence |
+| Autonomous convergence governance | Program gate (`min-success-rate` + `max-risk-level`) + audit JSON output | Program completion is policy-verified and traceable |
+| Measurable outcomes | KPI automation (`value metrics snapshot/baseline/trend`) | Delivery quality can be tracked week-over-week |
+| Tool-agnostic adoption | Works across Claude/Cursor/Windsurf/Copilot/Kiro | No lock-in to a single AI IDE |
+| Built-in governance | Docs governance, lock management, audit, env/workspace controls | Team collaboration stays auditable and stable |
+
+### 90-Second Value Proof
+
+```bash
+# 1) Adopt kse in current repo
+kse adopt
+
+# 2) Generate Spec workflow draft
+kse spec bootstrap --name 01-00-demo-feature --non-interactive
+
+# 3) Generate KPI input sample
+kse value metrics sample --out ./kpi-input.json --json
+
+# 4) Produce machine-readable KPI snapshot
+kse value metrics snapshot --input ./kpi-input.json --json
+```
+
 ---
 
 ## Quick Start
@@ -224,6 +254,7 @@ sequenceDiagram
 - 📦 **[Multi-Repository Management](docs/multi-repo-management-guide.md)** - Manage multiple Git repositories
 - 🎭 **[Scene Runtime](docs/scene-runtime-guide.md)** - Template engine, quality pipeline, ontology, Moqui ERP
 - 🤖 **[Multi-Agent Coordination](docs/multi-agent-coordination-guide.md)** - Parallel agent coordination
+- 📈 **[Value Observability](docs/value-observability-guide.md)** - KPI snapshot, baseline, trend, gate-ready evidence
 - 🔌 **[Integration Modes](docs/integration-modes.md)** - Three ways to integrate kse
 - 📝 **[Command Reference](docs/command-reference.md)** - All kse commands
 
@@ -243,6 +274,10 @@ sequenceDiagram
 ### Advanced Topics
 - [Adoption Guide](docs/adoption-guide.md) - Adopting kse in existing projects
 - [Upgrade Guide](docs/upgrade-guide.md) - Version upgrade instructions
+- [Release Archive](docs/releases/README.md) - Versioned release notes and validation report index
+- [Release Notes v1.46.2](docs/releases/v1.46.2.md) - Current release highlights and impact
+- [Validation Report v1.46.2](docs/releases/v1.46.2-validation.md) - Release-readiness evidence and verification results
+- [Release Checklist](docs/release-checklist.md) - Repeatable pre-release verification flow
 - [Manual Workflows](docs/manual-workflows-guide.md) - Step-by-step workflows
 - [Developer Guide](docs/developer-guide.md) - Contributing and extending kse
 
@@ -255,6 +290,10 @@ sequenceDiagram
 
 ### Autonomous Control 🚀 NEW in v1.23.0
 - **Fully Autonomous Execution**: AI independently manages entire development workflows from requirements to delivery
+- **Closed-Loop Program Execution**: `kse auto close-loop "<goal>"` runs from goal decomposition to terminal orchestration state without manual confirmation gates
+- **Automatic Master/Sub Portfolio Split**: Large goals are auto-split into dependency-wired sub-specs and coordinated by a master spec
+- **Semantic Decomposition + Live Stream**: Clause/category-aware goal parsing plus live orchestration status stream (disable via `--no-stream`)
+- **Session Resume + Retention Hygiene**: Resume interrupted runs with `--resume latest` and maintain archives via `kse auto session list/prune`
 - **Intelligent Error Recovery**: Automatically diagnose and fix errors with 3 retry attempts and learning system
 - **Strategic Checkpoints**: Pause only at meaningful milestones (phase boundaries, fatal errors, external resources)
 - **Continuous Task Execution**: Execute multiple tasks without interruption between individual tasks
@@ -267,6 +306,9 @@ sequenceDiagram
 
 **Quick Start**:
 ```bash
+# Decompose one broad goal into master/sub specs and run to closure
+kse auto close-loop "build autonomous close-loop and master/sub multi-spec execution for kse"
+
 # Create and execute a feature autonomously
 kse auto create "user authentication with JWT tokens"
 
@@ -285,6 +327,13 @@ kse auto resume
 ### Spec-Driven Development
 Structure your work with Requirements → Design → Tasks workflow
 
+### KPI Automation & Observability 🚀 NEW in v1.46.2
+- **Unified Metric Contract**: Load and validate KPI definitions from `metric-definition.yaml`
+- **Weekly Snapshot Pipeline**: Generate machine-readable snapshots with risk level and audit reasons
+- **Baseline and Trend Analysis**: Build baseline from historical data and detect worsening trends automatically
+- **Gate-Ready Summary**: Emit Day30/Day60-consumable summary payloads with evidence paths
+- **CLI Commands**: `value metrics sample`, `value metrics snapshot`, `value metrics baseline`, `value metrics trend` with `--json` support
+
 ### Multi-Workspace Management 🚀 NEW in v1.11.0
 - **Workspace Registry**: Manage multiple kse projects from a single location
 - **Quick Switching**: Switch between projects without directory navigation
@@ -479,6 +528,10 @@ English and Chinese interfaces
 kse adopt                          # Adopt kse in existing project
 kse create-spec <name>             # Legacy: create empty Spec folder only
 
+# Autonomous close-loop program (one command, no confirmation loop)
+kse auto close-loop "<goal>"       # Auto split goal into master/sub specs and execute to closure
+kse auto close-loop "<goal>" --dry-run --json  # Preview decomposition plan only
+
 # Spec workflow (recommended)
 kse spec bootstrap --name <spec> --non-interactive         # Generate requirements/design/tasks draft
 kse spec pipeline run --spec <spec>                         # Run staged workflow for one Spec
@@ -491,6 +544,14 @@ kse spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # Multi-Spec
 kse context export <spec-name>     # Export context for AI tools
 kse prompt generate <spec> <task>  # Generate task-specific prompt
 
+# KPI automation and observability (NEW in v1.46.2)
+kse value metrics sample --out <path> --json               # Generate sample KPI input JSON
+kse value metrics snapshot --input <path> --json          # Generate weekly KPI snapshot + gate summary
+kse value metrics baseline --from-history <N> --json      # Build baseline from earliest N snapshots
+kse value metrics trend --window <N> --json               # Analyze trend/risk from latest N snapshots
+kse auto kpi trend --weeks 8 --period week --json         # Aggregate autonomous delivery KPI trend (weekly/daily buckets + anomalies)
+kse auto kpi trend --weeks 8 --period day --csv --out <path> # Export autonomous KPI trend as CSV
+
 # Workspace management (NEW in v1.11.0)
 kse workspace create <name> [path] # Register a new workspace
 kse workspace list                 # List all workspaces
@@ -596,9 +657,8 @@ See [Command Reference](docs/command-reference.md) for complete documentation.
 ### Getting Help
 
 - 📖 **Documentation**: Start with the [Quick Start Guide](docs/quick-start.md)
-- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/yourusername/kiro-spec-engine/issues)
-- 💬 **Discussions**: [GitHub Discussions](https://github.com/yourusername/kiro-spec-engine/discussions)
-- 📧 **Email**: support@example.com
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/heguangyong/kiro-spec-engine/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/heguangyong/kiro-spec-engine/discussions)
 
 ### Contributing
 
@@ -611,7 +671,7 @@ We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for:
 ### Development Setup
 
 ```bash
-git clone https://github.com/yourusername/kiro-spec-engine.git
+git clone https://github.com/heguangyong/kiro-spec-engine.git
 cd kiro-spec-engine
 npm install
 npm link  # For local development
@@ -676,5 +736,5 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 ---
 
 **Version**: 1.46.2  
-**Last Updated**: 2026-02-13
+**Last Updated**: 2026-02-14
 

package/README.zh.md

@@ -46,6 +46,36 @@ graph LR
 - ✅ 构建需要清晰需求和设计的功能的任何人
 - ✅ 受益于 Spec 驱动开发的项目
 
+## 为什么 kse 更有优势
+
+| 优势点 | kse 能力 | 实际收益 |
+| --- | --- | --- |
+| 结构化先行 | 需求 → 设计 → 任务 + gate 检查 | 降低返工和需求漂移 |
+| 自动闭环交付 | 单命令闭环（`auto close-loop`） | 不再分步骤等待人工确认 |
+| 多 Agent 扩展 | DAG 编排（`orchestrate run/status/stop`） | 并行交付，不再手工开多终端 |
+| 自动主从拆分 | 目标自动拆成 Master/Sub Spec 并建立依赖 | 复杂需求自动转成可并行执行计划 |
+| 程序级自愈闭环 | `auto close-loop-program` 自动恢复 + 策略记忆 | 失败/部分失败会自动续跑，直到有界收敛 |
+| 自治收敛治理 | Program Gate（最小成功率 + 最大风险）+ 审计 JSON 导出 | 完成结果可按策略验收且全程可追溯 |
+| 结果可量化 | KPI 自动化（`value metrics snapshot/baseline/trend`） | 周度趋势可追踪、可审计 |
+| 工具无锁定 | 兼容 Claude/Cursor/Windsurf/Copilot/Kiro | 团队可保留现有 AI 工具链 |
+| 治理内建 | 文档治理、锁机制、审计、环境/工作区管理 | 协作更稳定，过程可回放 |
+
+### 90 秒价值验证
+
+```bash
+# 1) 在当前仓库启用 kse
+kse adopt
+
+# 2) 生成 Spec 工作流草稿
+kse spec bootstrap --name 01-00-demo-feature --non-interactive
+
+# 3) 生成 KPI 输入样例
+kse value metrics sample --out ./kpi-input.json --json
+
+# 4) 产出机器可读 KPI 快照
+kse value metrics snapshot --input ./kpi-input.json --json
+```
+
 ---
 
 ## 快速开始
@@ -220,6 +250,7 @@ sequenceDiagram
 - 📄 **[文档治理](docs/document-governance.md)** - 自动化文档管理
 - 🎭 **[场景运行时指南](docs/scene-runtime-guide.md)** - 模板引擎、质量流水线、Ontology、Moqui ERP
 - 🤖 **[多 Agent 协调指南](docs/multi-agent-coordination-guide.md)** - 多 Agent 并行协调
+- 📈 **[Value 可观测指南](docs/zh/value-observability-guide.md)** - KPI 快照、基线、趋势与门禁证据
 - 🔌 **[集成模式](docs/integration-modes.md)** - 三种集成 kse 的方式
 - 📝 **[命令参考](docs/command-reference.md)** - 所有 kse 命令
 
@@ -239,6 +270,10 @@ sequenceDiagram
 ### 高级主题
 - [采用指南](docs/adoption-guide.md) - 在现有项目中采用 kse
 - [升级指南](docs/upgrade-guide.md) - 版本升级说明
+- [发布归档](docs/zh/releases/README.md) - 版本化发布说明与验证报告入口
+- [发布说明 v1.46.2](docs/zh/releases/v1.46.2.md) - 当前版本更新亮点
+- [验证报告 v1.46.2](docs/zh/releases/v1.46.2-validation.md) - 发布就绪验证与证据结果
+- [发布检查清单](docs/zh/release-checklist.md) - 可重复执行的发版前核验流程
 - [手动工作流](docs/manual-workflows-guide.md) - 分步工作流
 - [开发者指南](docs/developer-guide.md) - 贡献和扩展 kse
 
@@ -249,9 +284,23 @@ sequenceDiagram
 
 ## 主要功能
 
+### Autonomous Control（自动闭环）🚀
+- **自动闭环推进**：`kse auto close-loop "<目标>"` 从目标拆分到编排完成全程自动推进
+- **自动主从拆分**：自动生成 Master/Sub Spec 组合、依赖关系与 Agent 分配
+- **语义分解 + 实时状态流**：按目标语义自动归类拆分，并实时输出编排进度（可用 `--no-stream` 关闭）
+- **会话恢复与归档治理**：支持 `--resume latest` 续跑，并可用 `kse auto session list/prune` 管理会话归档
+- **终态收敛**：输出统一执行结果（completed/failed/stopped），避免中途等待人工逐步确认
+
 ### Spec 驱动开发
 使用需求 → 设计 → 任务工作流结构化你的工作
 
+### KPI 自动化与可观测 🚀 v1.46.2 新增
+- **统一指标契约**：从 `metric-definition.yaml` 加载并校验 KPI 定义
+- **周快照流水线**：生成包含风险级别和审计原因的 machine-readable 快照
+- **基线与趋势分析**：基于历史快照生成 baseline，并自动识别连续恶化趋势
+- **门禁可复用摘要**：输出 Day30/Day60 可直接消费的 summary 与证据路径
+- **CLI 命令**：`value metrics sample`、`value metrics snapshot`、`value metrics baseline`、`value metrics trend`，支持 `--json`
+
 ### 多工作区管理 🚀 v1.11.0 新功能
 - **工作区注册表**：从单一位置管理多个 kse 项目
 - **快速切换**：无需目录导航即可在项目间切换
@@ -396,6 +445,10 @@ kse orchestrate stop
 kse adopt                          # 在现有项目中采用 kse
 kse create-spec <name>             # 兼容旧版：仅创建空 Spec 目录
 
+# 自动闭环主从编排（单命令）
+kse auto close-loop "<目标>"        # 自动拆分 Master/Sub Spec 并推进到完成态
+kse auto close-loop "<目标>" --dry-run --json  # 仅预览拆分与依赖计划
+
 # Spec 工作流（推荐）
 kse spec bootstrap --name <spec> --non-interactive          # 生成 requirements/design/tasks 初稿
 kse spec pipeline run --spec <spec>                         # 对单个 Spec 执行分阶段流程
@@ -408,6 +461,14 @@ kse spec gate run --specs "<spec-a,spec-b>" --max-parallel <N>     # 多 Spec
 kse context export <spec-name>     # 为 AI 工具导出上下文
 kse prompt generate <spec> <task>  # 生成任务特定提示
 
+# KPI 自动化与可观测（v1.46.2 新增）
+kse value metrics sample --out <path> --json               # 生成 KPI 输入样例 JSON
+kse value metrics snapshot --input <path> --json          # 生成周度 KPI 快照 + gate 摘要
+kse value metrics baseline --from-history <N> --json      # 从最早 N 个快照生成 baseline
+kse value metrics trend --window <N> --json               # 基于最近 N 个快照分析趋势与风险
+kse auto kpi trend --weeks 8 --period week --json         # 聚合自动交付 KPI 趋势（支持周/日桶 + 异常信号）
+kse auto kpi trend --weeks 8 --period day --csv --out <path> # 以 CSV 导出自动 KPI 趋势
+
 # 工作区管理（v1.11.0 新增）
 kse workspace create <name> [path] # 注册新工作区
 kse workspace list                 # 列出所有工作区
@@ -539,6 +600,6 @@ kse spec bootstrap --name 01-00-my-first-feature --non-interactive
 ---
 
 **版本**：1.46.2  
-**最后更新**：2026-02-13
+**最后更新**：2026-02-14
 
 

package/bin/kiro-spec-engine.js

@@ -17,6 +17,7 @@ const registerCollabCommands = require('../lib/commands/collab');
 const { registerSpecBootstrapCommand } = require('../lib/commands/spec-bootstrap');
 const { registerSpecPipelineCommand } = require('../lib/commands/spec-pipeline');
 const { registerSpecGateCommand } = require('../lib/commands/spec-gate');
+const { registerValueCommands } = require('../lib/commands/value');
 const VersionChecker = require('../lib/version/version-checker');
 
 const i18n = getI18n();
@@ -657,6 +658,9 @@ registerKnowledgeCommands(program);
 const { registerOrchestrateCommands } = require('../lib/commands/orchestrate');
 registerOrchestrateCommands(program);
 
+// Value realization and observability commands
+registerValueCommands(program);
+
 // Template management commands
 const templatesCommand = require('../lib/commands/templates');
 

package/docs/OFFLINE_INSTALL.md

@@ -1,166 +1,96 @@
-# kiro-spec-engine v1.24.1 离线安装指南
-
-由于 GitHub 账号问题，无法通过 npm 在线安装。请使用以下方法进行离线安装。
-
-## 方法 1: 直接从源码安装（推荐）
-
-### 步骤：
-
-1. **将整个项目目录复制到目标机器**
-   ```bash
-   # 压缩当前目录（排除 node_modules）
-   # Windows PowerShell:
-   Compress-Archive -Path * -DestinationPath kse-v1.24.1.zip -Exclude node_modules,coverage,.git
-   ```
-
-2. **在目标机器上解压并安装依赖**
-   ```bash
-   # 解压文件
-   Expand-Archive kse-v1.24.1.zip -DestinationPath kse-v1.24.1
-   cd kse-v1.24.1
-   
-   # 安装依赖
-   npm install
-   ```
-
-3. **全局安装**
-   ```bash
-   npm install -g .
-   ```
-
-4. **验证安装**
-   ```bash
-   kse --version
-   # 应该显示: 1.24.1
-   ```
-
-## 方法 2: 创建 npm 包（如果 npm 可用）
-
-### 步骤：
-
-1. **在当前目录创建 npm 包**
-   ```bash
-   npm pack
-   # 会生成: kiro-spec-engine-1.24.1.tgz
-   ```
-
-2. **将 .tgz 文件复制到目标机器**
-
-3. **在目标机器上安装**
-   ```bash
-   npm install -g kiro-spec-engine-1.24.1.tgz
-   ```
-
-## 方法 3: 手动复制（最简单）
-
-### 步骤：
-
-1. **复制以下文件/目录到目标机器**
-   - `bin/` - CLI 入口
-   - `lib/` - 核心代码
-   - `template/` - 模板文件
-   - `locales/` - 国际化文件
-   - `docs/` - 文档
-   - `package.json` - 包配置
-   - `README.md` - 说明文档
-   - `LICENSE` - 许可证
-
-2. **在目标目录安装依赖**
-   ```bash
-   npm install --production
-   ```
-
-3. **创建全局链接**
-   ```bash
-   npm link
-   ```
-
-## 依赖列表
-
-如果目标机器无法访问 npm registry，需要手动下载以下依赖：
-
-```json
-{
-  "chalk": "^4.1.2",
-  "chokidar": "^3.5.3",
-  "cli-table3": "^0.6.5",
-  "commander": "^9.0.0",
-  "fs-extra": "^10.0.0",
-  "inquirer": "^8.2.0",
-  "js-yaml": "^4.1.1",
-  "minimatch": "^10.1.1",
-  "path": "^0.12.7",
-  "semver": "^7.5.4",
-  "simple-git": "^3.30.0"
-}
+# kse 离线安装指南
+
+> 适用于无法直接访问 npm registry 的环境。
+
+---
+
+**版本**: 1.46.2  
+**最后更新**: 2026-02-14
+
+---
+
+## 前置条件
+
+- Node.js >= 16
+- npm 可用（建议 npm >= 8）
+
+验证：
+
+```bash
+node --version
+npm --version
 ```
 
-## 验证安装
+---
+
+## 方式 1：使用 `.tgz` 离线包安装（推荐）
 
-安装完成后，运行以下命令验证：
+1. 获取离线包文件（示例：`kiro-spec-engine-1.46.2.tgz`）。
+2. 在目标机器执行：
 
 ```bash
-# 检查版本
-kse --version
+npm install -g kiro-spec-engine-1.46.2.tgz
+```
+
+3. 验证：
 
-# 查看帮助
+```bash
+kse --version
 kse --help
+```
 
-# 初始化项目
-cd your-project
-kse adopt
+---
+
+## 方式 2：从源码离线安装
+
+1. 将项目目录复制到目标机器（建议排除 `node_modules/.git/coverage`）。
+2. 在目标机器安装依赖并全局安装：
+
+```bash
+npm install
+npm install -g .
 ```
 
-## 新功能（v1.24.1）
+3. 验证：
+
+```bash
+kse --version
+```
 
-- ✅ 嵌套 Git 仓库支持
-- ✅ 多仓库管理增强
-- ✅ 跨平台路径处理改进
+---
 
-## 故障排除
+## Windows 常见问题
 
-### 问题 1: npm 命令不可用（Windows 常见问题）
+### 问题：`npm` 命令不可用
 
-**症状**: 提示 "无法将 npm 项识别为 cmdlet"
+症状：PowerShell 提示无法识别 `npm`。
 
-**原因**: PowerShell 会话未刷新环境变量
+解决：
 
-**解决方案**:
 ```powershell
-# 方法 1: 临时添加 Node.js 到 PATH（推荐）
 $env:Path = "C:\Program Files\nodejs;$env:Path"
 npm --version
-
-# 方法 2: 重启 PowerShell/终端
-
-# 方法 3: 使用完整路径
-& "C:\Program Files\nodejs\npm.cmd" --version
 ```
 
-### 问题 2: 命令找不到
-```bash
-# 检查全局安装路径
-npm config get prefix
+---
 
-# 确保该路径在 PATH 环境变量中
-```
+## 安装后建议的 90 秒验证
 
-### 问题 3: 依赖安装失败
 ```bash
-# 使用淘宝镜像
-npm install --registry=https://registry.npmmirror.com
+cd your-project
+kse adopt
+kse spec bootstrap --name 01-00-demo-feature --non-interactive
+kse value metrics sample --out ./kpi-input.json --json
+kse value metrics snapshot --input ./kpi-input.json --json
 ```
 
-### 问题 4: 权限错误
-```bash
-# Windows: 以管理员身份运行
-# Linux/Mac: 使用 sudo
-sudo npm install -g .
-```
+如果最后一步成功，说明你的环境已经可以输出机器可读 KPI 结果（用于周度评审和门禁证据）。
+
+---
 
-## 联系支持
+## 相关文档
 
-如有问题，请查看：
-- 文档: `docs/README.md`
-- 快速开始: `docs/quick-start.md`
-- 故障排除: `docs/troubleshooting.md`
+- [文档索引](README.md)
+- [快速入门](quick-start.md)
+- [命令参考](command-reference.md)
+- [Value 可观测指南](value-observability-guide.md)