kiro-spec-engine 1.4.4 → 1.5.2

package/docs/troubleshooting.md

@@ -18,6 +18,7 @@
 - [Command Issues](#command-issues)
 - [Integration Issues](#integration-issues)
 - [Watch Mode Issues](#watch-mode-issues)
+- [Document Governance Issues](#document-governance-issues)
 - [Platform-Specific Issues](#platform-specific-issues)
 - [Getting More Help](#getting-more-help)
 
@@ -566,6 +567,337 @@ kse context export 01-00-user-login
 
 ---
 
+## Document Governance Issues
+
+### Diagnostic not finding violations
+
+**Symptoms:**
+```bash
+$ kse docs diagnose
+✅ Project is compliant
+# But you know there are temporary files
+```
+
+**Cause:** Files don't match temporary patterns or are in unexpected locations
+
+**Solutions:**
+
+**1. Check what patterns are configured:**
+```bash
+kse docs config
+# Look at "Temporary Patterns" section
+```
+
+**2. Add custom patterns if needed:**
+```bash
+kse docs config --set temporary-patterns "*-SUMMARY.md,SESSION-*.md,*-COMPLETE.md,TEMP-*.md,WIP-*.md,MVP-*.md,DRAFT-*.md"
+```
+
+**3. Manually check for violations:**
+```bash
+# Check root directory
+ls *.md
+
+# Should only see: README.md, README.zh.md, CHANGELOG.md, CONTRIBUTING.md
+```
+
+---
+
+### Cleanup not removing files
+
+**Symptoms:**
+```bash
+$ kse docs cleanup
+Deleted 0 file(s)
+# But temporary files still exist
+```
+
+**Possible Causes & Solutions:**
+
+**1. Files don't match temporary patterns:**
+```bash
+# Check file names
+ls *.md
+
+# If file is "notes.md" (doesn't match patterns)
+# Either rename it to match pattern or delete manually
+mv notes.md TEMP-notes.md
+kse docs cleanup
+```
+
+**2. Files are in subdirectories:**
+```bash
+# Cleanup only checks root and Spec directories
+# Check subdirectories manually
+find . -name "*-SUMMARY.md"
+```
+
+**3. Permission issues:**
+```bash
+# Check file permissions
+ls -la *.md
+
+# Fix if needed
+chmod u+w filename.md
+kse docs cleanup
+```
+
+---
+
+### Archive moving files to wrong subdirectory
+
+**Symptoms:**
+```bash
+$ kse docs archive --spec my-spec
+# Files moved to unexpected subdirectories
+```
+
+**Cause:** File type classification based on filename
+
+**Solution:**
+
+**Understand classification rules:**
+- **scripts/** - `.js`, `.py`, `.sh`, "script" in name
+- **reports/** - "report", "analysis", "summary" in name
+- **tests/** - `.test.js`, `.spec.js`, "test" in name
+- **results/** - "result", "output" in name
+- **docs/** - Everything else
+
+**Rename files to match intended subdirectory:**
+```bash
+# Want file in reports/
+mv data.md analysis-report.md
+
+# Want file in scripts/
+mv tool.js test-script.js
+
+# Then archive
+kse docs archive --spec my-spec
+```
+
+---
+
+### Git hooks not blocking commits
+
+**Symptoms:**
+```bash
+$ git commit -m "Add feature"
+# Commit succeeds even with violations
+```
+
+**Possible Causes & Solutions:**
+
+**1. Hooks not installed:**
+```bash
+# Check status
+kse docs hooks status
+
+# If not installed
+kse docs hooks install
+```
+
+**2. Hook file not executable:**
+```bash
+# Check permissions (macOS/Linux)
+ls -la .git/hooks/pre-commit
+
+# Make executable
+chmod +x .git/hooks/pre-commit
+```
+
+**3. Using --no-verify flag:**
+```bash
+# This bypasses hooks
+git commit --no-verify -m "message"
+
+# Remove --no-verify to enable validation
+git commit -m "message"
+```
+
+**4. Not a git repository:**
+```bash
+# Check if .git exists
+ls -la .git/
+
+# If not, initialize git
+git init
+kse docs hooks install
+```
+
+---
+
+### Validation failing for valid structure
+
+**Symptoms:**
+```bash
+$ kse docs validate --spec my-spec
+❌ Missing required file: requirements.md
+# But the file exists
+```
+
+**Possible Causes & Solutions:**
+
+**1. File in wrong location:**
+```bash
+# Check exact path
+ls -la .kiro/specs/my-spec/requirements.md
+
+# Should be directly in Spec directory, not in subdirectory
+```
+
+**2. Wrong Spec name:**
+```bash
+# Check Spec directory name
+ls .kiro/specs/
+
+# Use exact name
+kse docs validate --spec 01-00-my-feature
+```
+
+**3. Case sensitivity (Linux/macOS):**
+```bash
+# File is "Requirements.md" but should be "requirements.md"
+mv Requirements.md requirements.md
+```
+
+---
+
+### Configuration changes not taking effect
+
+**Symptoms:**
+```bash
+$ kse docs config --set root-allowed-files "README.md,CUSTOM.md"
+✅ Configuration updated
+
+$ kse docs diagnose
+# Still reports CUSTOM.md as violation
+```
+
+**Cause:** Configuration file not being read or cached
+
+**Solutions:**
+
+**1. Verify configuration was saved:**
+```bash
+# Check config file
+cat .kiro/config/docs.json
+
+# Should show your changes
+```
+
+**2. Check for typos in key name:**
+```bash
+# Wrong: root-files
+# Correct: root-allowed-files
+
+kse docs config --set root-allowed-files "README.md,CUSTOM.md"
+```
+
+**3. Restart any running processes:**
+```bash
+# If watch mode is running
+kse watch stop
+kse watch start
+```
+
+---
+
+### "Permission denied" when installing hooks
+
+**Symptoms:**
+```bash
+$ kse docs hooks install
+Error: EACCES: permission denied, open '.git/hooks/pre-commit'
+```
+
+**Cause:** Insufficient permissions for .git/hooks directory
+
+**Solutions:**
+
+**1. Check directory permissions:**
+```bash
+ls -la .git/hooks/
+```
+
+**2. Fix permissions:**
+```bash
+# Make hooks directory writable
+chmod u+w .git/hooks/
+
+# Try again
+kse docs hooks install
+```
+
+**3. Check if file is read-only:**
+```bash
+# If pre-commit already exists
+ls -la .git/hooks/pre-commit
+
+# Remove read-only flag
+chmod u+w .git/hooks/pre-commit
+```
+
+---
+
+### Stats showing no data
+
+**Symptoms:**
+```bash
+$ kse docs stats
+⚠️  No execution history found
+```
+
+**Cause:** No governance commands have been run yet
+
+**Solution:**
+
+**Run some governance commands:**
+```bash
+# Run diagnostic
+kse docs diagnose
+
+# Run cleanup
+kse docs cleanup --dry-run
+
+# Now check stats
+kse docs stats
+```
+
+**Note:** Only actual operations are logged (not --dry-run for cleanup/archive)
+
+---
+
+### Report generation fails
+
+**Symptoms:**
+```bash
+$ kse docs report
+Error: ENOENT: no such file or directory, open '.kiro/reports/...'
+```
+
+**Cause:** Reports directory doesn't exist
+
+**Solution:**
+
+**Create reports directory:**
+```bash
+mkdir -p .kiro/reports
+
+# Try again
+kse docs report
+```
+
+**Or let kse create it:**
+```bash
+# Run diagnostic first (creates directory structure)
+kse docs diagnose
+
+# Then generate report
+kse docs report
+```
+
+---
+
 ## Platform-Specific Issues
 
 ### Windows Issues
@@ -771,6 +1103,7 @@ Error: EINVAL: invalid filename
 3. **Spec name format** - Use XX-YY-feature-name format
 4. **Context too large** - Use task-specific prompts
 5. **Watch mode** - Restart or check configuration
+6. **Document governance** - Check patterns and permissions
 
 **Quick Fixes:**
 ```bash
@@ -785,6 +1118,12 @@ ls -la .kiro/specs/
 
 # Test context export
 kse context export spec-name
+
+# Check document compliance
+kse docs diagnose
+
+# Clean up temporary files
+kse docs cleanup --dry-run
 ```
 
 **Still stuck?** → [Create an issue](https://github.com/kiro-spec-engine/kse/issues/new)

package/docs/zh/spec-numbering-guide.md

@@ -0,0 +1,348 @@
+# Spec 编号策略指南
+
+> 为你的 Spec 选择合适编号策略的完整指南
+
+## 概述
+
+Kiro Spec Engine 使用两部分编号系统：`{主序号}-{从序号}-{描述}`
+
+- **主序号**：代表功能领域或主题（01, 02, 03, ...）
+- **从序号**：代表该领域内的迭代或子功能（00, 01, 02, ...）
+- **描述**：使用 kebab-case 格式的 Spec 描述
+
+**示例**：
+- `01-00-user-authentication`（用户认证）
+- `01-01-add-oauth-support`（添加 OAuth 支持）
+- `02-00-payment-system`（支付系统）
+
+## 何时使用主序号 vs 从序号
+
+### 策略 1：简单项目（推荐大多数情况）
+
+**适用场景**：少于 20 个独立功能的项目
+
+**方法**：只使用主序号，从序号始终为 `00`
+
+```
+01-00-user-authentication      # 用户认证
+02-00-payment-integration      # 支付集成
+03-00-notification-system      # 通知系统
+04-00-reporting-dashboard      # 报表仪表板
+05-00-api-gateway              # API 网关
+```
+
+**优点**：
+- ✅ 简单清晰
+- ✅ 一目了然
+- ✅ 无需提前规划分组
+- ✅ 适合独立功能
+
+**何时使用**：
+- 构建工具或库
+- 功能相对独立
+- 项目处于早期阶段
+- 小团队（< 5 人）
+
+### 策略 2：按主题分组的复杂项目
+
+**适用场景**：具有明确功能领域的大型项目
+
+**方法**：将相关 Spec 归入同一主序号
+
+```
+# 用户管理领域 (01-xx)
+01-00-user-authentication-foundation    # 用户认证基础
+01-01-add-oauth-support                 # 添加 OAuth 支持
+01-02-add-two-factor-auth               # 添加双因素认证
+01-03-add-sso-integration               # 添加 SSO 集成
+
+# 支付领域 (02-xx)
+02-00-payment-system-mvp                # 支付系统 MVP
+02-01-add-subscription-billing          # 添加订阅计费
+02-02-add-invoice-generation            # 添加发票生成
+02-03-add-refund-workflow               # 添加退款流程
+
+# 通知领域 (03-xx)
+03-00-notification-email                # 邮件通知
+03-01-notification-sms                  # 短信通知
+03-02-notification-push                 # 推送通知
+03-03-notification-in-app               # 应用内通知
+```
+
+**优点**：
+- ✅ 清晰的主题分组
+- ✅ 易于追踪功能演进
+- ✅ 显示 Spec 之间的关系
+- ✅ 适合大型项目扩展
+
+**何时使用**：
+- 构建复杂应用
+- 功能有明确的领域（用户、支付、通知等）
+- 每个领域预期有多次迭代
+- 大团队且有领域负责人
+
+### 策略 3：混合方法（灵活）
+
+**适用场景**：从简单开始，按需添加结构
+
+**方法**：初期只用主序号，需要时引入从序号
+
+**阶段 1 - 早期开发**：
+```
+01-00-mvp-core-features        # MVP 核心功能
+02-00-user-management          # 用户管理
+03-00-data-storage             # 数据存储
+04-00-api-gateway              # API 网关
+```
+
+**阶段 2 - 需要迭代时**：
+```
+01-00-mvp-core-features
+02-00-user-management
+03-00-data-storage-basic
+03-01-data-storage-add-caching      ← 添加迭代
+03-02-data-storage-add-replication  ← 添加迭代
+04-00-api-gateway
+05-00-monitoring-system
+```
+
+**优点**：
+- ✅ 从简单开始，按需增长
+- ✅ 无需过早规划
+- ✅ 适应项目演进
+- ✅ 兼具两种策略的优点
+
+**何时使用**：
+- 项目范围不确定
+- 需要灵活性
+- 敏捷开发方式
+- 学习 Spec 工作流
+
+## 语义化编号规则
+
+### 规则 1：XX-00 用于首个或独立 Spec
+
+使用 `XX-00` 表示：
+- 某个领域的第一个 Spec
+- 不需要迭代的独立功能
+- 独立的功能模块
+
+```
+01-00-authentication-system    # 领域首个
+02-00-payment-integration      # 独立功能
+03-00-email-notifications      # 独立模块
+```
+
+### 规则 2：XX-01+ 用于迭代和增强
+
+使用 `XX-01`、`XX-02` 等表示：
+- 与之前 Spec 相关的 bug 修复
+- 功能增强
+- 同一主题的迭代
+- 相关功能
+
+```
+01-00-authentication-system
+01-01-fix-session-timeout-bug       # Bug 修复
+01-02-add-remember-me-feature       # 功能增强
+01-03-add-password-reset            # 相关功能
+```
+
+### 规则 3：保持相关 Spec 在一起
+
+将以下 Spec 分组：
+- 共享相同代码库区域
+- 相互依赖
+- 属于同一功能领域
+- 由同一团队维护
+
+```
+# 好：相关通知功能分组
+03-00-notification-email
+03-01-notification-sms
+03-02-notification-push
+
+# 避免：不相关功能使用同一主序号
+03-00-notification-email
+03-01-payment-refunds        # ❌ 与通知无关
+```
+
+## 实际案例
+
+### 案例 1：工具/库项目（kiro-spec-engine）
+
+**项目类型**：具有独立功能的 CLI 工具
+
+**策略**：简单编号（XX-00）
+
+```
+01-00-user-space-diagnosis              # 用户空间诊断
+02-00-oauth-api-upgrade                 # OAuth API 升级
+03-00-multi-user-collaboration          # 多用户协作
+04-00-watch-mode-automation             # Watch 模式自动化
+05-00-agent-hooks-and-automation        # Agent Hooks 和自动化
+06-00-test-stability-and-reliability    # 测试稳定性和可靠性
+07-00-user-onboarding-and-documentation # 用户引导和文档
+08-00-document-lifecycle-management     # 文档生命周期管理
+09-00-document-governance-automation    # 文档治理自动化
+```
+
+**原因**：每个功能都是独立且完整的
+
+### 案例 2：电商平台
+
+**项目类型**：复杂 Web 应用
+
+**策略**：主题分组
+
+```
+# 用户领域
+01-00-user-registration-and-login       # 用户注册和登录
+01-01-user-profile-management           # 用户资料管理
+01-02-user-preferences-and-settings     # 用户偏好和设置
+
+# 商品领域
+02-00-product-catalog-foundation        # 商品目录基础
+02-01-product-search-and-filters        # 商品搜索和筛选
+02-02-product-recommendations           # 商品推荐
+
+# 订单领域
+03-00-shopping-cart-system              # 购物车系统
+03-01-checkout-process                  # 结账流程
+03-02-order-tracking                    # 订单追踪
+03-03-order-history                     # 订单历史
+
+# 支付领域
+04-00-payment-gateway-integration       # 支付网关集成
+04-01-multiple-payment-methods          # 多种支付方式
+04-02-payment-security-enhancements     # 支付安全增强
+```
+
+**原因**：明确的领域划分，每个领域有多个相关功能
+
+### 案例 3：SaaS 应用
+
+**项目类型**：多租户 SaaS
+
+**策略**：混合方法
+
+```
+# 核心功能（独立）
+01-00-tenant-management                 # 租户管理
+02-00-user-authentication               # 用户认证
+03-00-billing-system                    # 计费系统
+
+# 分析领域（分组）
+04-00-analytics-foundation              # 分析基础
+04-01-analytics-custom-dashboards       # 自定义仪表板
+04-02-analytics-export-reports          # 导出报表
+
+# 集成领域（分组）
+05-00-api-gateway                       # API 网关
+05-01-webhook-system                    # Webhook 系统
+05-02-third-party-integrations          # 第三方集成
+
+# 更多独立功能
+06-00-email-templates                   # 邮件模板
+07-00-notification-center               # 通知中心
+```
+
+**原因**：独立功能和分组领域的混合
+
+## 决策树
+
+使用此流程图决定编号策略：
+
+```
+这是你的第一个 Spec 吗？
+├─ 是 → 使用 01-00-{描述}
+└─ 否 → 继续...
+
+这与现有 Spec 相关吗？
+├─ 是 → 使用相同主序号，递增从序号
+│        示例：01-00 已存在 → 使用 01-01
+└─ 否 → 继续...
+
+你预期这个领域会有多次迭代吗？
+├─ 是 → 为该领域规划主序号
+│        示例：03-00, 03-01, 03-02 用于通知
+└─ 否 → 使用下一个可用主序号配 -00
+         示例：05-00-new-feature
+```
+
+## 最佳实践
+
+### ✅ 应该做
+
+1. **从简单开始**：在需要复杂性之前使用 XX-00
+2. **保持一致**：每个项目坚持一种策略
+3. **记录你的方法**：在项目 README 中添加说明
+4. **使用描述性名称**：让描述清晰明了
+5. **预留主序号**：如果规划领域，预留范围
+
+### ❌ 不应该做
+
+1. **不要过度规划**：不要提前创建 50 个主序号
+2. **不要混合不相关功能**：保持主序号的主题性
+3. **不要跳过数字**：使用连续编号
+4. **不要中途改变策略**：坚持你的方法
+5. **不要压力过大**：编号是为了组织，不是追求完美
+
+## 策略迁移
+
+### 从简单到主题化
+
+如果你从简单编号开始，需要添加结构：
+
+**之前**：
+```
+01-00-user-auth
+02-00-user-profile
+03-00-payment-basic
+04-00-payment-subscriptions
+```
+
+**之后**（可选重组）：
+```
+01-00-user-auth
+01-01-user-profile          # 与认证分组
+02-00-payment-basic
+02-01-payment-subscriptions # 与支付分组
+```
+
+**注意**：重命名现有 Spec 是可选的。你可以保留旧编号，从现在开始使用新策略。
+
+## 工具支持
+
+Kiro Spec Engine 提供命令帮助编号：
+
+```bash
+# 列出所有 Spec 及其编号
+kse status
+
+# 按主序号分组查看 Spec
+kse workflows
+
+# 获取下一个可用编号建议
+kse workflows --suggest-next
+```
+
+## 总结
+
+**根据项目复杂度选择策略**：
+
+- **简单项目**：所有使用 `XX-00`
+- **复杂项目**：按领域分组使用 `XX-YY`
+- **不确定**：从简单开始，稍后添加结构
+
+**记住**：目标是组织和清晰，而不是完美。选择适合你的团队和项目的方式。
+
+---
+
+**相关文档**：
+- [Spec 工作流指南](./spec-workflow.md)
+- [快速开始指南](./quick-start.md)
+- [常见问题](./faq.md)
+
+**版本**：1.0  
+**最后更新**：2026-01-24