@gordon.gan/specflow 1.3.3-beta → 1.4.1

package/skills/database/redis/references/redis-conf-production.md

@@ -0,0 +1,139 @@
+# Redis 生产配置最佳实践
+
+## 推荐生产配置 (redis.conf)
+
+```conf
+# ────────────────────────────────────
+# 基础配置
+# ────────────────────────────────────
+daemonize no
+pidfile /var/run/redis_6379.pid
+port 6379
+bind 0.0.0.0                        # 生产环境改为内网 IP
+protected-mode yes
+
+# ────────────────────────────────────
+# 内存管理
+# ────────────────────────────────────
+maxmemory 4gb
+maxmemory-policy allkeys-lru
+maxmemory-samples 10                # LRU 采样样本数 (越大越精确)
+
+# ────────────────────────────────────
+# 持久化 — 混合模式
+# ────────────────────────────────────
+save 900 1
+save 300 10
+save 60 10000
+stop-writes-on-bgsave-error yes
+rdbcompression yes
+rdbchecksum yes
+dbfilename dump.rdb
+dir /data/redis/
+
+appendonly yes
+appendfilename "appendonly.aof"
+appendfsync everysec
+no-appendfsync-on-rewrite no
+auto-aof-rewrite-percentage 100
+auto-aof-rewrite-min-size 64mb
+aof-load-truncated yes
+aof-use-rdb-preamble yes             # 混合持久化 (Redis 4.0+)
+
+# ────────────────────────────────────
+# 网络与连接
+# ────────────────────────────────────
+tcp-backlog 511
+timeout 300
+tcp-keepalive 300
+maxclients 10000
+
+# ────────────────────────────────────
+# 复制
+# ────────────────────────────────────
+replica-serve-stale-data yes
+replica-read-only yes
+repl-diskless-sync no
+repl-diskless-sync-delay 5
+repl-disable-tcp-nodelay no
+replica-priority 100
+
+# ────────────────────────────────────
+# 安全
+# ────────────────────────────────────
+requirepass your-strong-password-here
+rename-command FLUSHALL ""
+rename-command FLUSHDB ""
+rename-command CONFIG ""
+rename-command SHUTDOWN ""
+rename-command DEBUG ""
+rename-command SLAVEOF ""
+
+# ────────────────────────────────────
+# 慢查询日志
+# ────────────────────────────────────
+slowlog-log-slower-than 10000       # 记录 >10ms 的命令
+slowlog-max-len 128
+
+# ────────────────────────────────────
+# 高级配置
+# ────────────────────────────────────
+hash-max-ziplist-entries 512
+hash-max-ziplist-value 64
+list-max-ziplist-size -2
+list-compress-depth 0
+set-max-intset-entries 512
+zset-max-ziplist-entries 128
+zset-max-ziplist-value 64
+
+hz 10
+dynamic-hz yes
+activedefrag yes                     # 自动碎片整理 (Redis 4.0+)
+```
+
+## Docker 部署
+
+```bash
+# 单机 Redis
+docker run -d --name redis \
+    -p 6379:6379 \
+    -v /data/redis/data:/data \
+    -v /data/redis/redis.conf:/usr/local/etc/redis/redis.conf \
+    redis:7-alpine redis-server /usr/local/etc/redis/redis.conf
+
+# Redis Cluster
+docker network create redis-cluster
+
+for port in 7000 7001 7002 7003 7004 7005; do
+    mkdir -p /data/redis/${port}
+    docker run -d --name redis-${port} \
+        --net redis-cluster \
+        -p ${port}:${port} \
+        -v /data/redis/${port}:/data \
+        redis:7-alpine redis-server \
+            --port ${port} \
+            --cluster-enabled yes \
+            --cluster-config-file nodes.conf \
+            --cluster-node-timeout 5000 \
+            --appendonly yes
+done
+
+# 创建集群
+docker exec redis-7000 redis-cli --cluster create \
+    192.168.1.100:7000 192.168.1.100:7001 192.168.1.100:7002 \
+    192.168.1.100:7003 192.168.1.100:7004 192.168.1.100:7005 \
+    --cluster-replicas 1
+```
+
+## 性能调优检查清单
+
+- [ ] `maxmemory` 设置为物理内存的 60-70%
+- [ ] `maxmemory-policy` 设为 `allkeys-lru`（缓存场景）
+- [ ] 禁用危险命令（FLUSHALL/CONFIG/EVAL...）
+- [ ] 慢查询阈值 ≤ 10ms
+- [ ] 连接池配置合理（maxTotal ≤ maxclients）
+- [ ] Big Key 已拆分或索引
+- [ ] 不分业务混用实例
+- [ ] 监控指标已接入（INFO 命令定期采集）
+- [ ] RDB + AOF 混合持久化已配置
+- [ ] 主从 / Sentinel / Cluster 已部署

package/skills/specflow-approval/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: specflow-approval
+description: "Post-refine technical approval document -- AI closed-loop check + code/baseline grounding + over-design guard + implementability assessment"
+---
+
+# SpecFlow: Approval
+
+> **HARD GATE**: phase must be `refined`. Run `/specflow:refine` first if not.
+> **HARD GATE**: User must confirm before `approval.md` is written to the change directory.
+> Approval does NOT advance phase — it produces an optional review artifact for human sign-off.
+
+## Purpose
+
+Approval is the **post-refine, pre-apply technical review pass**: it reads the four
+refined artifacts (`proposal.md`, delta `specs/`, `design.md`, `tasks.md`), **grounds them
+against existing project code and spec baseline**, and produces a single `approval.md`
+technical-approval document for human sign-off.
+
+It is **optional**. Skip it when you want to go straight from refine to apply. Use it when
+the change is significant enough to warrant formal technical review before implementation
+begins — architecture decisions, cross-team impact, regulatory exposure, or any change where
+"should we even build this, this way?" deserves a documented answer.
+
+Unlike `/specflow:review` (which reviews code after implementation) and `/specflow:verify`
+(which validates implementation against specs), approval reviews the **plan** before any
+code is written. It fills the gap between refine convergence and apply execution.
+
+Approval does five things a deterministic CLI cannot:
+
+1. **Integrates** the four artifacts into a single narrative with cross-references.
+2. **Checks closed-loop coherence** across requirements ↔ design ↔ specs ↔ tasks using
+   semantic reasoning (fuzzy wording detection, coverage gaps, traceability).
+3. **Grounds the plan against reality** — reads existing project code (anchor files) and
+   the main spec baseline to verify the plan can actually land on this codebase.
+4. **Guards design quality** — detects over-engineering (YAGNI violations) while confirming
+   reasonable extensibility is preserved.
+5. **Assesses implementability** — can an engineer execute this plan without getting stuck?
+
+## Invocation
+
+```text
+/specflow:approval <change-name>
+```
+
+Cursor: `specflow:approval <change-name>`;Codex: `$specflow-approval <change-name>`.
+
+## Prerequisites
+
+- An active change exists with `.specflow.yaml` and `phase: refined`.
+  - If phase is not `refined`, REFUSE to proceed and suggest: "This change is in phase
+    `<phase>`. Run `/specflow:refine` first to complete deep review before generating an
+    approval document."
+- All four refined artifacts exist in `specflow/changes/<name>/`:
+  - `proposal.md`
+  - `specs/**/*.md` (at least one delta spec)
+  - `design.md`
+  - `tasks.md`
+- `specflow` CLI is available on PATH (for `specflow validate` and optional status lookup).
+- Optional: `explore.md` with `Status: confirmed` (enriches the approval's "why" section).
+
+## Artifact Language Setup
+
+Read `.claude/specflow/prompts/shared/artifact-language.md` and resolve the active planning
+root's `specflow/config.yaml` before generating `approval.md`. Apply the policy to all
+human-readable narrative content (summaries, assessments, evidence). Preserve protocol
+markers (`### Requirement:`, `#### Scenario:`, `- **WHEN**`, `- **THEN**`), capability IDs,
+change names, file paths, commands, and code in their original form.
+
+---
+
+## Stage 1: Pre-flight Validation
+
+1. Read `.specflow.yaml` and confirm `phase: refined`. If not, refuse and suggest `/specflow:refine`.
+2. Confirm all four artifacts exist. If any is missing, stop and tell the user which are missing.
+3. Read `specflow/config.yaml` and resolve `artifacts.language` (default `en`).
+4. Detect project tech stack signals at the project root only (do not recurse):
+   - `package.json` → Node/TS/JS ecosystem
+   - `go.mod` → Go
+   - `pyproject.toml` / `requirements.txt` → Python
+   - `Cargo.toml` → Rust
+   - `tsconfig.json` → TypeScript (refines Node detection)
+   - If none match, set `techStack: unknown`
+5. **Detect database stack** (for §4.4 guidance). Follow
+   `prompts/approval/database-guidance.md` §1 — set
+   `dbStack: mysql|postgresql|oracle|redis|elasticsearch|none`. Prefer OLTP
+   (`mysql`/`postgresql`/`oracle`) over cache/search when multiple match.
+6. Read `specflow/specs/` baseline if it exists (for Pass 7 baseline cross-check).
+
+Announce: "Generating technical approval document for change `<name>` (phase=refined, language=<lang>, techStack=<stack>, dbStack=<db>)."
+
+---
+
+## Stage 2: Load Execution Instructions
+
+Read these files and follow them:
+
+1. `.claude/specflow/prompts/approval/generate.md` (or repo `prompts/approval/generate.md`)
+2. `prompts/approval/database-guidance.md` — DB skill router for **local** packs under
+   `skills/database/` (in-repo maintenance; **no remote skill dependency**). **Not an MCP
+   tool**: on `dbStack` hit, `Read` matched `SKILL.md` + focused references; on `none`,
+   LLM-only §4.4.
+
+`generate.md` + `database-guidance.md` together specify:
+
+- The 7-dimension closed-loop verification (Passes 1–7, each with AI self-prompt, verdict rules, evidence format)
+- The design quality assessment (over-engineering signals + extensibility signals)
+- The architecture design (Mermaid diagrams + **图要点说明** + core-component table)
+- The detailed design generation (设计要点一览 + Happy Path 完整时序 + 业务场景时序与说明 +
+  data ER/DDL + interfaces inventory/fields/examples/errors + logic/config/compat)
+- The test strategy (layered test matrix mapped to §5 acceptance criteria)
+- The deployment/release/rollback plan
+- The implementability assessment (7 dimensions with verdict rules)
+- The approval document structure and generation rules
+- Protocol-marker preservation and language policy enforcement
+- §1 绪论与边界 (proposal + optional explore + AI; absorbs What/Impact; **no 变更摘要 chapter**;
+  pain-point diagram, User Journey, Non-Goals with reasons)
+- Document order: §1 绪论 → §2 评估 → §3 架构 → §4 详细设计 → **§5 验收标准** → §6 测试 → …
+- **Quality Gates G1–G4** + **Style & Tone** (hard rules in generate.md Part E)
+- **DB guidance router** (`database-guidance.md` + local `skills/database/`): match project
+  stack → Read in-repo skill; no hit → LLM fallback; **never** fetch remote skills / MCP wrap
+- Anchor-file extraction and code-reading rules (depth: anchor file only, no recursion)
+
+You MUST read `generate.md` before performing any analysis or writing `approval.md`. Do not
+invent the assessment dimensions or document structure — they are defined in that prompt.
+
+---
+
+## Stage 3: Extract Anchor Files
+
+Before running the closed-loop passes, extract the set of **anchor files** that the plan
+references. These are the files Pass 6 (Code Grounding) will read.
+
+**Extraction rules** (defined in detail in `generate.md` Part A → Pass 6):
+
+1. Scan `design.md` and `tasks.md` for file path references (backtick-quoted paths, code
+   blocks, or inline paths like `src/core/...`).
+2. Collect only paths under the project root that look like source files (`.ts`, `.js`,
+   `.py`, `.go`, `.rs`, `.kt`, `.java`, etc.) or config files (`package.json`, `tsconfig.json`,
+   etc.).
+3. Deduplicate. Do NOT read directories, only files.
+4. **Depth limit: read the anchor file itself only.** Do not follow imports, do not recurse.
+5. If no anchor files are found and the project has no source code (greenfield), Pass 6
+   will emit `skipped (greenfield — no existing code)`. If the project HAS source code but
+   the plan references no existing files, that is a `FAIL` (plan is ungrounded).
+
+Announce the extracted anchor file list to the user before Pass 1 begins.
+
+---
+
+## Stage 4: AI Closed-Loop Verification
+
+Perform the 7 closed-loop passes defined in `generate.md`, in order:
+
+### Internal coherence (Passes 1–5)
+
+1. **Pass 1 — Requirement Closure**: proposal ↔ specs coverage
+2. **Pass 2 — Design Closure**: design decisions ↔ spec requirements
+3. **Pass 3 — Spec Closure**: scenario completeness + testability (3-level grading) + delta integrity
+4. **Pass 4 — Implementation Closure**: tasks ↔ spec requirements coverage + granularity
+5. **Pass 5 — Risk Closure**: risks ↔ mitigations + BREAKING migration + unidentified risks
+
+### External grounding (Passes 6–7)
+
+6. **Pass 6 — Code Grounding**: design/tasks anchor files exist in the project + structure
+   compatibility + tech-stack consistency. Reads actual project code (anchor files only).
+7. **Pass 7 — Baseline Cross-Check**: delta specs vs `specflow/specs/` main baseline —
+   conflict detection, duplicate-definition detection, MODIFIED name matching.
+
+Each Pass must produce a brief result for the conversation (verdict + one-line evidence).
+Do **not** dump full coverage matrices into chat unless the user asks or a Pass is
+`WARNING`/`FAIL`.
+
+### Closed-Loop Overall Verdict
+
+After all 7 Passes:
+
+- `FAIL` if any Pass is `FAIL`
+- `PASS WITH WARNINGS` if no `FAIL` but at least one `WARNING`
+- `PASS` if all Passes are `PASS` (a `SKIPPED` Pass does not affect the verdict)
+
+When writing `approval.md` **§8**, use the **single compact table** only (see generate.md
+Part E §8): no per-Pass long sections, no duplicate summary table. Expand evidence only
+for ⚠️/❌ rows (max 2–3 bullets).
+
+---
+
+## Stage 5: Design Quality Assessment
+
+Perform the two design-quality checks defined in `generate.md` Part B:
+
+### Over-Engineering Check
+
+Scan `design.md` and `tasks.md` for the 5 over-engineering signals:
+
+1. Interface for unrequested requirements
+2. Unnecessary abstraction layers
+3. Pre-built unused infrastructure
+4. Config fields beyond current needs
+5. Complexity exceeding problem scale
+
+**Verdict rule**: 1 signal → `WARNING`; 3+ signals → `FAIL`; 0 signals → `PASS`.
+
+### Extensibility Assessment
+
+Scan `design.md` for the 5 extensibility signals:
+
+1. Namespace reservation
+2. Stable interface, replaceable implementation
+3. Explicit Non-Goals
+4. Backward-compatibility path
+5. Decision rationale mentions extensibility trade-off
+
+**Verdict rule**: 4-5 signals present → `PASS`; 2-3 → `WARNING`; 0-1 → `WARNING`.
+
+### Combined Design Quality Verdict
+
+- `FAIL` if over-engineering is `FAIL`
+- `WARNING` if either check is `WARNING`
+- `PASS` if both are `PASS`
+- **Special**: if over-engineering = `WARNING`/`FAIL` AND extensibility = `WARNING` →
+  escalate to `FAIL` (the plan is both bloated AND not extensible)
+
+---
+
+## Stage 6: Architecture Design
+
+Produce the **architecture design** section (approval.md **§3** 架构整体设计) defined in
+`generate.md` Part E. This answers "what modules make up the system, how they depend on
+and interact with each other, and what each module's responsibility and boundary is."
+
+It is complementary to Detailed Design: architecture is about **module-to-module
+relationships** (macro), detailed design is about **module-internal implementation**
+(micro). Architecture is placed **before** acceptance criteria so implementers read
+structure first.
+
+### 3.1 Overall Architecture
+
+Draw Mermaid diagram(s) — module dependency / layered and optionally system interaction:
+
+Requirements:
+
+1. **Mark changed modules** (`[新增]` / `[修改]`) so the change surface is visible.
+2. Label edges with dependency direction or interaction messages.
+3. Project-type mapping: CLI/library → `src/core/*`, `src/cli/*`; Web → services/components;
+   multi-repo → repositories/services.
+4. Consistent with **§2** decisions.
+5. **Hard rule — 图要点说明**: every architecture diagram MUST be followed by a numbered
+   「设计说明 / 图要点」list (boundaries, invariants, reuse vs new) — not a restatement of
+   node names. Align with scenario-job-compile §3 style.
+
+### 3.2 Core Components
+
+| Component | Responsibility | Boundary (does / does NOT) | Depends on | Change type |
+|-----------|---------------|----------------------------|-----------|-------------|
+
+Requirements: list added+modified components;「不做什么」boundaries; 1:1 with diagram;
+trace to §2 decisions. Optional short「组件边界总原则」list.
+
+**If no architecture change**: write explicit `不涉及架构变更(...)` marker.
+
+### 3.3 Architecture Consistency Self-check
+
+- Diagrams mark added/modified modules; each has 图要点说明.
+- Each component has a "does NOT do" boundary; diagram ↔ table 1:1.
+- Boundaries trace to §2 decisions.
+
+Present the architecture design to the user as part of the confirmation summary.
+
+---
+
+## Stage 7: Detailed Design
+
+Produce the **detailed design** section (approval.md **§4** 方案详细设计) defined in
+`generate.md` Part E.
+
+**Selective** categories; uninvolved ones get explicit「不涉及 X」markers.
+
+Order and hard requirements (from `generate.md` §4.1–4.8):
+
+1. **设计要点一览** — P1…Pn invariants from design decisions (required).
+2. **核心业务时序 · Happy Path** — complete Mermaid `sequenceDiagram` for the main success
+   path + post-diagram「设计要点」(required).
+3. **业务场景时序** — each scenario: purpose + diagram + **设计要点说明** (required notes;
+   bare diagrams fail quality).
+4. **数据结构** — Before drafting §4.4: follow `database-guidance.md`. If `dbStack` hit,
+   `Read` `skills/database/<stack>/SKILL.md` (+ DDL/index/JSON refs as needed).
+   If `none`, LLM-only with SpecFlow §4.4 hard bar (ER + full CREATE TABLE + field tables…).
+5. **接口设计** — inventory + fields + examples + errors…
+6. **核心算法 / 配置 / 兼容性** — as applicable.
+
+**Traceability**: every element → **§5** Requirement/Scenario and **§2** decision.
+If not implementer-ready, mark `[待 refine 澄清: <元素>]`.
+
+Present the detailed design to the user as part of the confirmation summary.
+
+---
+
+## Stage 8: Acceptance Criteria (after design)
+
+Produce **§5 验收标准** only **after** §3 architecture and §4 detailed design are drafted
+in the document order. Exhaustive Requirement + Scenario list with 3-level testability.
+Do not place acceptance before the design chapters.
+
+---
+
+## Stage 9: Test Strategy
+
+Produce the **test strategy** section (approval.md **§6** 测试策略). Every §5 acceptance
+criterion maps to ≥1 test layer with tools and verifiable goals.
+
+---
+
+## Stage 10: Deployment & Release
+
+Produce the **deployment / release / rollback** section (approval.md **§7**).
+
+---
+
+## Stage 11: Implementability Assessment
+
+Perform the 7 implementability dimensions defined in `generate.md` Part C.
+
+1. **Completeness** — no TODOs, placeholders, vague tasks
+2. **Spec Alignment** — tasks cover all spec requirements, no scope creep
+3. **Task Actionability** — can an engineer execute each task without ambiguity
+4. **Technical Feasibility** — design decisions are achievable in the detected tech stack
+5. **Dependency Clarity** — task dependencies and external dependencies are explicit
+6. **Architecture Consistency** — design choices match project's existing tech stack, directory structure, error-handling patterns, and test framework (grounded in code reading from Pass 6)
+7. **Implementation Risk** — high-risk module changes, data migration, concurrency, external API breaks, team tech-stack unfamiliarity
+
+Each dimension produces a verdict (`READY` | `NEEDS REFINEMENT` | `BLOCKED`) with evidence.
+
+### Implementability Overall Verdict
+
+- `BLOCKED` if any dimension is `BLOCKED`
+- `NEEDS REFINEMENT` if no `BLOCKED` but any dimension is `NEEDS REFINEMENT`
+- `READY` if all 7 are `READY`
+
+---
+
+## Stage 12: Generate approval.md
+
+Following the document structure and generation rules in `generate.md` Part E, produce
+`approval.md` inside the change directory at `specflow/changes/<name>/approval.md`.
+
+Document chapter order (hard):
+
+1. §1 绪论与边界 (proposal + optional explore + AI; includes What/Impact; **no 变更摘要**)
+2. §2 技术方案评估
+3. §3 架构整体设计 (图 + **图要点说明** + 组件)
+4. §4 方案详细设计 (设计要点 + Happy Path + 业务场景说明 + 数据/接口…)
+5. §5 验收标准 (**after** design)
+6. §6 测试策略 → §7 部署 → §8 闭环 → §9 可实施性 → §10 审批
+
+Key rules:
+
+- §1 truthful: pains from proposal/design/confirmed explore; User Journey → §5; Non-Goals with reasons; What/Impact in §1.2.
+- Decision Review includes every `design.md` decision.
+- §5 Acceptance exhaustive with 3-level testability; placed after §3/§4.
+- §3 every architecture diagram has「设计说明 / 图要点」; component table with「不做什么」.
+- §4 has 设计要点一览, complete Happy Path sequence + notes, each business scenario with 设计要点; DB/API hard bars (§4.4/§4.5).
+- **Quality Gates G1–G4**: >5-line prose flow → Mermaid; interfaces need failure examples; JSON/new-column need存量填充策略; rollback data compatibility explicit.
+- **Style & Tone**: plain language; gloss obscure abbreviations on first use; ban「尽量/大概/一般情况下」; use「必须/禁止/采用 XX 方案」.
+- **§8 闭环**: one compact table only; PASS one line; ⚠️/❌ ≤3 bullets; no per-Pass essays.
+- Test Strategy maps every §5 criterion to ≥1 layer.
+- Deployment selective; Code Grounding cites real files; sign-off blank; never recommend approve if any verdict is `FAIL`.
+
+---
+
+## Gate: User Confirmation
+
+Present a summary to the user:
+
+- Closed-loop overall verdict (PASS / PASS WITH WARNINGS / FAIL)
+- Design quality verdict (PASS / WARNING / FAIL)
+- Implementability overall verdict (READY / NEEDS REFINEMENT / BLOCKED)
+- AI pre-approval recommendation (建议批准 / 有条件批准 / 退回 refine / 拒绝)
+- The path where `approval.md` will be written
+
+Ask explicitly:
+
+> "确认生成审批文档并写入 `specflow/changes/<name>/approval.md`?"
+
+Do NOT write the file until the user confirms. If the user wants changes to the assessment,
+re-run the relevant Pass or dimension and update the summary before re-asking.
+
+On confirmation:
+
+1. Write `approval.md` to the change directory.
+2. Do NOT change `phase` — it remains `refined`.
+3. Report the file path and next-step suggestions.
+
+---
+
+## Stage 13: Next-Step Suggestions
+
+Based on the assessment results:
+
+- **If closed-loop = PASS, design quality = PASS, and implementability = READY**:
+  Suggest `/specflow:apply` to begin implementation.
+
+- **If any verdict is WARNING**:
+  Suggest the user either (a) proceed to `/specflow:apply` after acknowledging the warnings
+  in the approval document, or (b) return to `/specflow:refine` to close the gaps first.
+
+- **If any verdict is FAIL or implementability = BLOCKED**:
+  Strongly recommend `/specflow:refine` to resolve the failures before implementation.
+  Do NOT suggest `/specflow:apply` — the plan is not ready.
+
+In all cases, remind the user that `approval.md` is an optional artifact: it does not block
+`/specflow:apply` (which only requires `phase=refined`), and it does not affect
+`/specflow:archive` (which scans `specs/`, not `approval.md`).
+
+---
+
+## Not Covered by Approval
+
+- No code implementation — `/specflow:apply` owns that.
+- No phase transition — phase stays `refined` until `/specflow:apply` advances it.
+- No spec validation — `/specflow:verify` owns delta + main spec regression checks.
+- No code review — `/specflow:review` owns post-implementation code quality checks.
+- No artifact modification — approval reads the four artifacts (and project code, read-only)
+  but never modifies them. If a Pass reveals a gap, the user returns to `/specflow:refine`
+  to fix it; approval only documents the finding.
+- No full codebase scan — approval reads only the anchor files extracted in Stage 3. Full
+  codebase investigation is `/specflow:explore`'s job.
+- Approval is **not** a gate for apply. It is a decision-support artifact for human review.