scene-capability-engine 3.0.0

package/docs/quick-start-with-ai-tools.md

@@ -0,0 +1,375 @@
+# 快速入门：配合 AI 工具使用 kse
+
+> 5分钟学会如何用 kse 配合 Claude、Cursor、Copilot 等 AI 工具
+
+---
+
+## ⚠️ 重要：kse 的定位
+
+**kse 不是独立开发工具，而是 AI 工具的增强器**
+
+```
+你的工作界面 = AI 工具（Codex/Claude/Cursor）
+kse 的角色 = 后台管理 Spec，为 AI 提供结构化上下文
+```
+
+**简单理解**：
+- ❌ kse 不是用来写代码的
+- ✅ kse 是用来**组织项目信息**，让 AI 更好地帮你写代码
+- ✅ 你主要在 AI 工具中工作，kse 在后台提供支持
+
+**三种使用模式**：
+1. **AI 主动调用 kse**（Windsurf/Cline）- 最佳，完全自动 ⭐
+2. **手动导出上下文**（Claude/ChatGPT）- 当前方式
+3. **Watch Mode 自动化**（所有工具）- 进阶用法
+
+**详细说明**：查看 [集成哲学文档](./integration-philosophy.md)
+
+---
+
+## 核心理念
+
+**kse 是什么？**
+- 一个 CLI 工具，帮你管理项目的 Spec（需求、设计、任务）
+- 生成结构化的上下文，让 AI 工具更好地理解你的项目
+
+**为什么需要 kse？**
+- AI 工具需要清晰的上下文才能生成高质量代码
+- kse 帮你组织和导出这些上下文
+- 让 AI 按照你的设计和规范工作
+
+---
+
+## 工作流程图
+
+```
+┌─────────────┐
+│  1. 用 kse  │
+│  创建 Spec  │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  2. 导出    │
+│  上下文     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  3. 复制到  │
+│  AI 工具    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  4. AI 帮你 │
+│  写代码     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  5. 更新    │
+│  任务状态   │
+└─────────────┘
+```
+
+---
+
+## 5分钟快速开始
+
+### 步骤 1：安装 kse
+
+```bash
+npm install -g kiro-spec-engine
+```
+
+### 步骤 2：初始化项目
+
+```bash
+cd your-project
+kse adopt
+```
+
+这会在项目中创建 `.kiro/` 目录。
+
+### 步骤 3：创建你的第一个 Spec
+
+```bash
+kse spec bootstrap --name 01-00-user-login --non-interactive
+```
+
+然后编辑生成的文件：
+- `.kiro/specs/01-00-user-login/requirements.md` - 写需求
+- `.kiro/specs/01-00-user-login/design.md` - 写设计
+- `.kiro/specs/01-00-user-login/tasks.md` - 列任务
+
+### 步骤 4：导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+这会生成：`.kiro/specs/01-00-user-login/context-export.md`
+
+### 步骤 5：使用 AI 工具
+
+#### 方式 A：Claude Code / ChatGPT
+
+1. 打开生成的 `context-export.md`
+2. 复制全部内容
+3. 粘贴到 Claude/ChatGPT 对话框
+4. 说："请帮我实现任务 1.1"
+
+#### 方式 B：Cursor
+
+1. 生成任务提示：
+   ```bash
+   kse prompt generate 01-00-user-login 1.1
+   ```
+
+2. 打开 Cursor Composer (Cmd+K)
+3. 粘贴生成的提示
+4. Cursor 会根据上下文生成代码
+
+#### 方式 C：GitHub Copilot
+
+1. 在代码文件中添加注释：
+   ```javascript
+   // Task 1.1: Implement user login
+   // See: .kiro/specs/01-00-user-login/design.md
+   ```
+
+2. Copilot 会根据 Spec 文件生成代码
+
+### 步骤 6：更新任务状态
+
+完成任务后，编辑 `tasks.md`：
+
+```markdown
+- [x] 1.1 实现用户登录功能  ← 改成 [x] 表示完成
+- [ ] 1.2 添加密码加密
+```
+
+---
+
+## 详细示例：用 Claude Code 实现登录功能
+
+### 1. 创建 Spec
+
+```bash
+kse spec bootstrap --name 01-00-user-login --non-interactive
+```
+
+### 2. 编写需求（requirements.md）
+
+```markdown
+# 用户登录功能
+
+## 1. 功能需求
+
+### 1.1 用户可以用邮箱和密码登录
+- 输入：邮箱、密码
+- 输出：登录成功返回 token，失败返回错误信息
+- 验证：邮箱格式、密码长度 >= 6
+```
+
+### 3. 编写设计（design.md）
+
+```markdown
+# 设计方案
+
+## 1. API 设计
+
+### 1.1 登录接口
+- 路径：POST /api/auth/login
+- 请求体：{ email: string, password: string }
+- 响应：{ token: string } 或 { error: string }
+
+## 2. 实现方案
+
+### 2.1 AuthController
+- validateEmail() - 验证邮箱格式
+- validatePassword() - 验证密码长度
+- login() - 处理登录逻辑
+```
+
+### 4. 列出任务（tasks.md）
+
+```markdown
+- [ ] 1.1 实现 AuthController 类
+- [ ] 1.2 实现邮箱验证
+- [ ] 1.3 实现密码验证
+- [ ] 1.4 实现登录逻辑
+- [ ] 1.5 编写单元测试
+```
+
+### 5. 导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+### 6. 在 Claude Code 中使用
+
+**对话示例**：
+
+```
+你：[粘贴 context-export.md 的全部内容]
+
+你：请帮我实现任务 1.1 "实现 AuthController 类"，
+    按照设计文档中的方案，用 TypeScript 实现。
+
+Claude：好的，我会根据设计文档实现 AuthController 类...
+[生成代码]
+
+你：很好！现在请为这个类编写单元测试。
+
+Claude：[生成测试代码]
+
+你：完美！请帮我更新 tasks.md，标记任务 1.1 为完成。
+
+[你手动更新 tasks.md：- [x] 1.1 实现 AuthController 类]
+```
+
+---
+
+## 不同 AI 工具的最佳实践
+
+### Claude Code / ChatGPT
+✅ **优势**：大上下文窗口，可以一次加载完整 Spec  
+📝 **用法**：复制 `context-export.md` 全部内容  
+💡 **技巧**：一次对话可以完成多个任务
+
+### Cursor
+✅ **优势**：IDE 集成，可以直接修改文件  
+📝 **用法**：用 `kse prompt generate` 生成任务提示  
+💡 **技巧**：使用 Composer 模式，让 Cursor 直接编辑文件
+
+### GitHub Copilot
+✅ **优势**：实时代码补全  
+📝 **用法**：在代码注释中引用 Spec 文件  
+💡 **技巧**：写详细的注释，Copilot 会根据 Spec 生成代码
+
+### Windsurf / Cline
+✅ **优势**：可以执行命令和修改文件  
+📝 **用法**：让 AI 直接运行 `kse` 命令  
+💡 **技巧**：AI 可以自动导出上下文和更新任务状态
+
+---
+
+## 常见问题
+
+### Q: 每次都要复制粘贴上下文吗？
+
+**A**: 取决于 AI 工具：
+- **Claude/ChatGPT**：是的，每次新对话需要重新加载
+- **Cursor**：可以在项目中持续使用，Cursor 会记住上下文
+- **Copilot**：不需要，它会自动读取项目文件
+
+### Q: 上下文太大怎么办？
+
+**A**: 使用任务级别的提示：
+```bash
+# 只导出特定任务的上下文
+kse prompt generate 01-00-user-login 1.1
+```
+
+### Q: AI 生成的代码不符合设计怎么办？
+
+**A**: 
+1. 检查 `design.md` 是否写得够详细
+2. 在提示中明确说："严格按照设计文档实现"
+3. 提供代码示例在设计文档中
+
+### Q: 如何让 AI 遵循项目规范？
+
+**A**: 使用 Steering Rules：
+```bash
+# 导出时包含规范
+kse context export 01-00-user-login --steering --steering-files=CORE_PRINCIPLES.md
+```
+
+### Q: 可以自动更新任务状态吗？
+
+**A**: 
+- **Kiro IDE**：支持自动更新
+- **其他工具**：需要手动更新 `tasks.md`
+- **未来**：计划支持更多工具的自动更新
+
+---
+
+## 进阶技巧
+
+### 1. 使用 Steering Rules 控制 AI 行为
+
+创建 `.kiro/steering/CODING_STANDARDS.md`：
+
+```markdown
+# 编码规范
+
+- 使用 TypeScript
+- 所有函数必须有 JSDoc 注释
+- 使用 async/await 而不是 Promise.then
+- 错误处理使用 try-catch
+```
+
+导出时包含：
+```bash
+kse context export 01-00-user-login --steering
+```
+
+### 2. 为不同工具生成不同格式的提示
+
+```bash
+# 为 Claude 生成
+kse prompt generate 01-00-user-login 1.1 --tool=claude-code
+
+# 为 Cursor 生成
+kse prompt generate 01-00-user-login 1.1 --tool=cursor
+
+# 通用格式
+kse prompt generate 01-00-user-login 1.1
+```
+
+### 3. 批量导出多个任务
+
+```bash
+# 导出整个 Spec
+kse context export 01-00-user-login
+
+# 然后在 AI 工具中说：
+# "请按顺序实现任务 1.1 到 1.5"
+```
+
+---
+
+## 总结
+
+**kse 的价值**：
+1. ✅ 结构化管理项目需求和设计
+2. ✅ 生成 AI 友好的上下文
+3. ✅ 让 AI 按照你的规范工作
+4. ✅ 跟踪任务进度
+
+**配合 AI 工具的流程**：
+1. 用 kse 写 Spec（需求、设计、任务）
+2. 导出上下文
+3. 复制给 AI 工具
+4. AI 帮你写代码
+5. 更新任务状态
+
+**下一步**：
+- 查看 [完整跨工具指南](./cross-tool-guide.md)
+- 查看 [命令参考](./command-reference.md)
+- 查看 [手动工作流指南](./manual-workflows-guide.md)
+
+---
+
+**开始使用！** 🚀
+
+```bash
+npm install -g kiro-spec-engine
+kse adopt
+kse spec bootstrap --name 01-00-my-feature --non-interactive
+```
+

package/docs/quick-start.md

@@ -0,0 +1,146 @@
+# Quick Start Guide
+
+> Get your project using Spec-driven development in 2 minutes
+
+---
+
+## What You'll Learn
+
+- ✅ Install kse and adopt it in your project
+- ✅ Tell your AI about the methodology
+- ✅ Let AI work according to Spec-driven approach
+
+## Why This Is Better Than Ad-hoc AI Prompting
+
+- Specs reduce ambiguity before coding starts.
+- Orchestrate mode scales from single feature to multi-Spec parallel delivery.
+- KPI commands make progress and risk measurable, not just "looks done".
+
+---
+
+## Step 1: Install kse (30 seconds)
+
+```bash
+npm install -g kiro-spec-engine
+```
+
+Verify:
+```bash
+kse --version
+```
+
+---
+
+## Step 2: Adopt in Your Project (30 seconds)
+
+```bash
+cd your-project
+kse adopt
+```
+
+This creates `.kiro/` directory with:
+- `README.md` - Project development guide
+- `steering/` - Development rules
+- `specs/` - Where Specs will live
+
+---
+
+## Step 3: Tell Your AI (1 minute)
+
+**In your AI tool (Cursor, Claude, Windsurf, etc.), say:**
+
+```
+Please read .kiro/README.md to understand how this project works.
+```
+
+**Your AI will learn:**
+- This project follows Spec-driven development
+- Every feature starts with a Spec (requirements + design + tasks)
+- How to work with this methodology
+
+---
+
+## Step 4: Start Working
+
+**Just ask your AI to implement features:**
+
+```
+I need a user login feature with email and password.
+```
+
+**Your AI will:**
+1. Bootstrap a Spec draft (`requirements/design/tasks`)
+2. Refine requirements and design with you
+3. Run the staged Spec workflow
+4. Implement according to the Spec
+
+**If you want to run commands manually:**
+
+```bash
+# Single-Spec recommended flow
+kse spec bootstrap --name 01-00-user-login --non-interactive
+kse spec pipeline run --spec 01-00-user-login
+kse spec gate run --spec 01-00-user-login --json
+
+# Multi-Spec flow (defaults to orchestrate mode)
+kse spec bootstrap --specs "01-00-user-login,01-01-user-session" --max-parallel 3
+kse spec pipeline run --specs "01-00-user-login,01-01-user-session" --max-parallel 3
+kse spec gate run --specs "01-00-user-login,01-01-user-session" --max-parallel 3
+```
+
+**The AI uses kse commands automatically** - you don't need to learn them.
+
+---
+
+## Optional Step 5: Verify Measurable Delivery (30 seconds)
+
+Generate a sample KPI input file:
+
+```bash
+kse value metrics sample --out ./kpi-input.json --period 2026-W10 --json
+```
+
+Then run:
+
+```bash
+kse value metrics snapshot --input ./kpi-input.json --json
+```
+
+If you prefer manual input, use:
+
+```json
+{
+  "period": "2026-W10",
+  "metrics": {
+    "ttfv_minutes": 25,
+    "batch_success_rate": 0.86,
+    "cycle_reduction_rate": 0.34,
+    "manual_takeover_rate": 0.16
+  },
+  "notes": "quick-start smoke run"
+}
+```
+
+This gives you a machine-readable snapshot with risk level and output paths.
+
+---
+
+## That's It!
+
+You're now using Spec-driven development. Your AI understands the methodology and will follow it.
+
+**Key insight:** You don't "use kse" - your project "follows Spec-driven methodology" and kse helps enforce it.
+
+---
+
+## Next Steps
+
+- **[Integration Modes](integration-modes.md)** - Understand how AI tools work with kse
+- **[Spec Workflow](spec-workflow.md)** - Deep dive into Spec creation
+- **[Tool Guides](tools/)** - Tool-specific tips
+
+---
+
+**Version**: 1.46.2  
+**Last Updated**: 2026-02-14
+

package/docs/release-checklist.md

@@ -0,0 +1,121 @@
+# Release Checklist
+
+> Minimal, repeatable checklist before publishing a new kse version.
+
+---
+
+## 1. Functional Verification
+
+```bash
+# Fast CI smoke suite (integration-focused)
+npm run test:smoke
+
+# Full regression suite (unit + integration + properties)
+npm run test:full
+
+# Guardrail: fail on newly introduced .skip tests
+npm run test:skip-audit
+
+# Unit tests for value observability commands
+npm test -- tests/unit/commands/value-metrics.test.js
+
+# CLI smoke checks
+node bin/kiro-spec-engine.js --help
+node bin/kiro-spec-engine.js value metrics --help
+```
+
+---
+
+## 2. Value Observability Smoke Flow
+
+```bash
+kse value metrics sample --out ./kpi-input.json --json
+kse value metrics snapshot --input ./kpi-input.json --json
+```
+
+Expected:
+
+- `sample` writes a valid JSON scaffold.
+- `snapshot` returns machine-readable result with `snapshot_path` and risk metadata.
+
+---
+
+## 3. Packaging Hygiene
+
+```bash
+npm pack --dry-run
+```
+
+Verify:
+
+- No transient artifacts (for example `__pycache__`, `*.pyc`) in tarball listing.
+- Tarball size remains within expected range for current release.
+
+---
+
+## 4. Documentation Consistency
+
+Check that key docs are aligned with current version and capabilities:
+
+- `README.md`
+- `README.zh.md`
+- `docs/command-reference.md`
+- `docs/quick-start.md`
+- `docs/zh/quick-start.md`
+- `CHANGELOG.md`
+
+Optional sanity scan:
+
+```bash
+rg -n "yourusername|support@example.com" README.md README.zh.md docs docs/zh -S
+
+# Canonical repository link check (should return no matches)
+rg -n "github.com/kiro-spec-engine/kse" README.md README.zh.md docs START_HERE.txt INSTALL_OFFLINE.txt -S -g "!docs/release-checklist.md" -g "!docs/zh/release-checklist.md"
+```
+
+---
+
+## 5. Git Readiness
+
+```bash
+git status -sb
+git log --oneline -n 15
+```
+
+Verify:
+
+- Working tree is clean.
+- Commits are logically grouped and messages are release-ready.
+
+---
+
+## 6. Publish Readiness
+
+Ensure:
+
+- `package.json` version is correct.
+- `CHANGELOG.md` includes release-relevant entries.
+- Release notes draft exists (for example `docs/releases/vX.Y.Z.md`).
+- Optional: configure release evidence gate with repository variables (`Settings -> Secrets and variables -> Actions -> Variables`):
+  - `KSE_RELEASE_GATE_ENFORCE`: `true|false` (default advisory, non-blocking)
+  - `KSE_RELEASE_GATE_REQUIRE_EVIDENCE`: require `handoff-runs.json` summary
+  - `KSE_RELEASE_GATE_REQUIRE_GATE_PASS`: require evidence gate `passed=true` (default true when evidence exists)
+  - `KSE_RELEASE_GATE_MIN_SPEC_SUCCESS_RATE`: minimum allowed success rate percent
+  - `KSE_RELEASE_GATE_MAX_RISK_LEVEL`: `low|medium|high|unknown` (default `unknown`)
+  - `KSE_RELEASE_GATE_MAX_UNMAPPED_RULES`: maximum allowed unmapped ontology business rules
+  - `KSE_RELEASE_GATE_MAX_UNDECIDED_DECISIONS`: maximum allowed undecided ontology decisions
+  - `KSE_RELEASE_GATE_REQUIRE_SCENE_BATCH_PASS`: require scene package publish-batch gate passed (`true|false`, default `true`)
+  - `KSE_RELEASE_GATE_MAX_SCENE_BATCH_FAILURES`: maximum allowed scene package batch failure count (default `0`)
+- Optional: tune release drift alerts in release notes:
+  - Drift evaluation is executed by `scripts/release-drift-evaluate.js` in CI (history load, alert calc, gate report writeback, enforce exit code).
+  - `KSE_RELEASE_DRIFT_ENFORCE`: `true|false` (default `false`), block publish when drift alerts are triggered
+  - `KSE_RELEASE_DRIFT_FAIL_STREAK_MIN`: minimum consecutive failed gates to trigger alert (default `2`)
+  - `KSE_RELEASE_DRIFT_HIGH_RISK_SHARE_MIN_PERCENT`: minimum high-risk share in latest 5 versions (default `60`)
+  - `KSE_RELEASE_DRIFT_HIGH_RISK_SHARE_DELTA_MIN_PERCENT`: minimum short-vs-long high-risk share delta (default `25`)
+  - `KSE_RELEASE_DRIFT_PREFLIGHT_BLOCK_RATE_MIN_PERCENT`: minimum release preflight blocked rate in latest 5 known runs (default `40`)
+  - `KSE_RELEASE_DRIFT_HARD_GATE_BLOCK_STREAK_MIN`: minimum consecutive hard-gate preflight blocked streak (latest window, default `2`)
+  - `KSE_RELEASE_DRIFT_PREFLIGHT_UNAVAILABLE_STREAK_MIN`: minimum consecutive release preflight unavailable streak (latest window, default `2`)
+- Optional local dry-run for gate history index artifact:
+  - `kse auto handoff gate-index --dir .kiro/reports/release-evidence --out .kiro/reports/release-evidence/release-gate-history.json --json`
+
+Then proceed with your release workflow (tag, push, npm publish, GitHub release).

package/docs/releases/README.md

@@ -0,0 +1,13 @@
+# Release Archive
+
+This directory stores release-facing documents:
+
+- release notes
+- validation reports
+- release process references
+
+## Available Versions
+
+- [Release checklist](../release-checklist.md)
+- [v1.46.2 release notes](./v1.46.2.md)
+- [v1.46.2 validation report](./v1.46.2-validation.md)

package/docs/releases/v1.46.2-validation.md

@@ -0,0 +1,45 @@
+# v1.46.2 Validation Report
+
+Validation date: 2026-02-14
+
+## Executed Checks
+
+1. Value metrics unit command tests
+
+```bash
+npm test -- tests/unit/commands/value-metrics.test.js
+```
+
+Result:
+
+- Test Suites: 1 passed
+- Tests: 9 passed
+
+2. CI test suite
+
+```bash
+npm run test:ci
+```
+
+Result:
+
+- Test Suites: 3 passed
+- Tests: 31 passed
+
+3. Packaging dry run
+
+```bash
+npm pack --dry-run
+```
+
+Result:
+
+- Tarball name: `kiro-spec-engine-1.46.2.tgz`
+- Package size: ~889.8 kB
+- Total files: 317
+- No transient Python bytecode artifacts observed in listing.
+
+## Notes
+
+- Value metrics command set includes `sample`, `snapshot`, `baseline`, and `trend`.
+- Error guidance for value metrics now includes actionable next commands.