devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/regression/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: regression
+description: This skill should be used when reviewing changes that may remove exports, change signatures, or alter behavior.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Regression Patterns
+
+Domain expertise for detecting functionality regressions and validating implementation intent. Use alongside `devflow:review-methodology` for complete regression reviews.
+
+## Iron Law
+
+> **WHAT WORKED BEFORE MUST WORK AFTER**
+>
+> Every change carries regression risk. Removed exports break consumers. Changed signatures
+> break callers. Modified behavior breaks expectations. The burden of proof is on the change:
+> demonstrate no regression, or document the intentional breaking change.
+
+---
+
+## Regression Categories
+
+### 1. Lost Functionality
+
+Features, exports, or capabilities that existed before but are missing after.
+
+| Type | Risk | Detection |
+|------|------|-----------|
+| Removed exports | Breaks consumers | Compare `export` statements |
+| Removed CLI options | Breaks scripts | Compare option definitions |
+| Removed API endpoints | Breaks clients | Compare route handlers |
+| Removed event handlers | Breaks integrations | Compare `.on()` calls |
+
+```typescript
+// VIOLATION: Export removed without deprecation
+// BEFORE: export function deleteUser(id: string): void { }
+// AFTER: (removed) - consumers will break!
+```
+
+### 2. Broken Behavior
+
+Code still exists but behaves differently in breaking ways.
+
+| Type | Risk | Detection |
+|------|------|-----------|
+| Changed return types | Null dereference | Compare function signatures |
+| Changed defaults | Unexpected behavior | Compare default values |
+| Removed side effects | Missing events/logs | Compare emit/log calls |
+| Changed error handling | Uncaught errors | Compare throw/return patterns |
+
+```typescript
+// VIOLATION: Return type widened without migration
+// BEFORE: function getUser(id: string): User { }
+// AFTER: function getUser(id: string): User | null { }
+// Callers assuming non-null will break!
+```
+
+### 3. Intent vs Reality Mismatch
+
+Commit message promises one thing, code does another.
+
+| Type | Risk | Detection |
+|------|------|-----------|
+| Commit says X, code does Y | False confidence | Compare message to diff |
+| Partial implementation | Incomplete feature | Check all stated changes |
+| Missing edge cases | Fragile code | Verify claimed coverage |
+
+```typescript
+// VIOLATION: Commit says "Add retry logic" but no retry implemented
+async function fetchData(): Promise<Data> {
+  return api.get('/data');  // No retry!
+}
+```
+
+### 4. Incomplete Migrations
+
+Old API deprecated but not all consumers updated.
+
+| Type | Risk | Detection |
+|------|------|-----------|
+| Some call sites updated | Mixed behavior | Search for old API usage |
+| Consumers not updated | Type errors | Check all importers |
+| Tests not updated | False passes | Compare test coverage |
+
+```typescript
+// VIOLATION: Migration incomplete
+// file1.ts: newFunction({ a, b })  // Updated
+// file2.ts: oldFunction(a, b)      // NOT updated!
+```
+
+---
+
+## Quick Detection Commands
+
+```bash
+# Find removed exports
+git diff main...HEAD | grep "^-export"
+
+# Find removed files
+git diff main...HEAD --name-status | grep "^D"
+
+# Find incomplete migration (old API still used)
+grep -r "oldFunction" src/ --include="*.ts"
+
+# Find new TODOs (incomplete work)
+git diff main...HEAD | grep "^\+.*TODO"
+```
+
+---
+
+## Extended References
+
+For extended examples and detection techniques:
+
+- **[violations.md](references/violations.md)** - Detailed violation examples for each category
+- **[patterns.md](references/patterns.md)** - Correct patterns for regression-safe changes
+- **[detection.md](references/detection.md)** - Comprehensive bash commands for detection
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria | Examples |
+|----------|----------|----------|
+| **CRITICAL** | Breaking changes without migration | Public exports removed, return types incompatible, required params added |
+| **HIGH** | Significant behavior changes | Defaults changed, error handling changed, side effects removed |
+| **MEDIUM** | Moderate regression risk | Internal APIs changed, logging reduced, performance changed |
+| **LOW** | Minor concerns | Documentation drift, internal refactoring |
+
+---
+
+## Regression Checklist
+
+Before approving changes:
+
+- [ ] No exports removed without deprecation
+- [ ] Return types backward compatible
+- [ ] Default values unchanged (or documented)
+- [ ] Side effects preserved (events, logging)
+- [ ] All consumers of changed code updated
+- [ ] Migration complete across codebase
+- [ ] CLI options preserved or deprecated
+- [ ] API endpoints preserved or versioned
+- [ ] Commit message matches implementation
+- [ ] Breaking changes documented in CHANGELOG

package/src/assets/skills/reliability/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: reliability
+description: This skill should be used when reviewing code for unbounded loops, missing assertions, excessive allocation, or deep indirection.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Reliability Patterns
+
+Domain expertise for runtime reliability and defensive bounds analysis. Use alongside `devflow:review-methodology` for complete reliability reviews.
+
+## Iron Law
+
+> **EVERY OPERATION MUST TERMINATE AND EVERY RESOURCE MUST BE BOUNDED**
+>
+> Adapted from NASA/JPL's "Power of Ten" rules for safety-critical code [1]: every loop must
+> have a fixed upper bound, every resource must have a known lifetime, and every assumption
+> must be checked by an assertion. Unbounded operations are latent outages.
+
+---
+
+## Reliability Categories
+
+### 1. Bounded Iteration [1]
+
+All loops, retries, and pagination must terminate after a known maximum.
+
+**Violation**: Unbounded retry loop
+```typescript
+while (true) {
+  const res = await fetch(url);
+  if (res.ok) break;
+  await sleep(1000);
+}
+```
+
+**Solution**: Fixed upper bound with explicit failure
+```typescript
+const MAX_RETRIES = 5;
+for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+  const res = await fetch(url);
+  if (res.ok) return res;
+  await sleep(1000 * 2 ** attempt);
+}
+throw new Error(`Failed after ${MAX_RETRIES} attempts`);
+```
+
+### 2. Assertion Density [1]
+
+Assert preconditions and invariants in production code, not just tests.
+
+**Violation**: Silent assumption
+```typescript
+function processPayment(order: Order) {
+  const total = order.items.reduce((sum, i) => sum + i.price, 0);
+  chargeCard(order.paymentMethod, total);
+}
+```
+
+**Solution**: Explicit precondition checks
+```typescript
+function processPayment(order: Order) {
+  assert(order.items.length > 0, 'Cannot process empty order');
+  assert(order.paymentMethod != null, 'Missing payment method');
+  const total = order.items.reduce((sum, i) => sum + i.price, 0);
+  assert(total > 0, 'Order total must be positive');
+  chargeCard(order.paymentMethod, total);
+}
+```
+
+### 3. Allocation Discipline [1]
+
+Minimize allocation in hot paths — prefer pre-sized collections, pools, or arenas.
+
+**Violation**: Allocation in tight loop
+```go
+func processEvents(events []Event) []Result {
+    var results []Result
+    for _, e := range events {
+        buf := make([]byte, 4096)  // alloc per iteration
+        results = append(results, process(e, buf))
+    }
+    return results
+}
+```
+
+**Solution**: Pre-allocate outside loop
+```go
+func processEvents(events []Event) []Result {
+    results := make([]Result, 0, len(events))
+    buf := make([]byte, 4096)  // single allocation
+    for _, e := range events {
+        results = append(results, process(e, buf))
+    }
+    return results
+}
+```
+
+### 4. Indirection Limits [1]
+
+Restrict pointer depth — no pointer-to-pointer, `Box<Box<T>>`, or triple-nested references.
+
+**Violation**: Excessive indirection
+```rust
+fn update(data: &mut Box<Box<Vec<Item>>>) {
+    (***data).push(item);
+}
+```
+
+**Solution**: Flatten indirection
+```rust
+fn update(data: &mut Vec<Item>) {
+    data.push(item);
+}
+```
+
+### 5. Metaprogramming Restraint [1]
+
+Restrict to simple constructs — no reflection-heavy magic, multi-level macros, or recursive generics.
+
+**Violation**: Recursive generic type
+```typescript
+type DeepPartial<T> = T extends object
+  ? { [K in keyof T]?: DeepPartial<T[K]> }
+  : T;
+type Config = DeepPartial<DeepPartial<AppConfig>>;  // unbounded recursion risk
+```
+
+**Solution**: Bounded, explicit type
+```typescript
+type ShallowPartial<T> = { [K in keyof T]?: T[K] };
+type ConfigOverrides = Pick<AppConfig, 'timeout' | 'retries'>;
+```
+
+---
+
+## Extended References
+
+| Reference | Content |
+|-----------|---------|
+| `references/sources.md` | Full bibliography |
+| `references/patterns.md` | Correct patterns with citations |
+| `references/violations.md` | Violation examples with citations |
+| `references/detection.md` | Grep patterns for automated scanning |
+
+## Severity Guidelines
+
+| Level | Criteria | Examples |
+|-------|----------|----------|
+| **CRITICAL** | Unbounded operation on external I/O | Infinite retry on network call, allocation in tight loop processing unbounded input |
+| **HIGH** | Implicit-only bounds, zero assertions in critical path | Retry with no max, validation function with no precondition checks |
+| **MEDIUM** | Missing bound on bounded data, low assertion density | Pagination without page limit on known-finite dataset, sparse assertions |
+| **LOW** | Style-level reliability improvement | Unnecessary indirection, overly complex generic type |

package/src/assets/skills/reliability/references/detection.md

@@ -0,0 +1,66 @@
+# Reliability — Detection Patterns
+
+Grep commands for automated detection of reliability violations.
+
+## Unbounded Loops
+
+```bash
+# while(true) / for(;;) patterns
+grep -rn 'while\s*(true)\|while\s*(1)\|for\s*(;;)' --include="*.ts" --include="*.tsx" --include="*.js"
+grep -rn 'while True' --include="*.py"
+grep -rn 'for\s*{' --include="*.go" | grep -v 'range\|select\|ctx'
+grep -rn 'while\s*(true)\|for\s*(;;)' --include="*.java"
+grep -rn 'loop\s*{' --include="*.rs"
+```
+
+## Missing Retry Bounds
+
+```bash
+# Retry/attempt keywords without max/limit/bound nearby
+grep -rn 'retry\|retries\|attempt' --include="*.ts" --include="*.tsx" | grep -v 'max\|limit\|bound\|MAX\|LIMIT'
+grep -rn 'retry\|retries\|attempt' --include="*.py" | grep -v 'max\|limit\|bound'
+grep -rn 'retry\|retries\|Retry' --include="*.go" | grep -v 'Max\|max\|Limit\|limit'
+grep -rn 'retry\|retries\|attempt' --include="*.java" | grep -v 'max\|limit\|MAX'
+```
+
+## Excessive Indirection
+
+```bash
+# Pointer-to-pointer (Go)
+grep -rn '\*\*[A-Z]' --include="*.go"
+# Double-boxed types (Rust)
+grep -rn 'Box<Box\|Rc<Rc\|Arc<Arc\|&&mut\|&mut &mut' --include="*.rs"
+# Triple-nested Map/Record (TypeScript)
+grep -rn 'Map<.*Map<.*Map<\|Record<.*Record<.*Record<' --include="*.ts" --include="*.tsx"
+```
+
+## Missing Assertions
+
+```bash
+# Functions with zero assert/invariant checks (heuristic: find functions > 10 lines)
+grep -rn 'function\|fn\s\|def\s\|public\s.*(' --include="*.ts" --include="*.go" --include="*.py" --include="*.java" --include="*.rs" | head -50
+# Compare against assertion density
+grep -rn 'assert\|invariant\|precondition\|require(' --include="*.ts" --include="*.go" --include="*.py" --include="*.java" --include="*.rs" | wc -l
+```
+
+## Allocation in Hot Paths
+
+```bash
+# new/make inside for loops (Go)
+grep -rn 'make(\|new(' --include="*.go" | grep -B5 'for\s\|range'
+# new allocation in loops (Java)
+grep -rn 'new\s' --include="*.java" | grep -B5 'for\s*(\|while\s*('
+# String concatenation in loops (Python)
+grep -rn '+=' --include="*.py" | grep -B3 'for\s\|while\s'
+```
+
+## Reflection and Dynamic Dispatch
+
+```bash
+# Java reflection
+grep -rn 'getClass()\|getMethod\|getDeclaredField\|Class.forName\|\.invoke(' --include="*.java"
+# Python dynamic attribute access
+grep -rn 'getattr\|setattr\|__getattr__\|eval(\|exec(' --include="*.py"
+# TypeScript runtime type checking (often unnecessary)
+grep -rn 'eval(\|Function(' --include="*.ts" --include="*.tsx"
+```

package/src/assets/skills/reliability/references/patterns.md

@@ -0,0 +1,151 @@
+# Reliability — Correct Patterns
+
+## 1. Bounded Iteration Patterns [1]
+
+### Bounded pagination
+```typescript
+const MAX_PAGES = 100;
+async function fetchAllPages(url: string) {
+  const results = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const data = await fetch(`${url}?page=${page}`);
+    results.push(...data.items);
+    if (!data.nextPage) break;
+  }
+  return results;
+}
+```
+
+### Bounded event consumer with context cancellation [2]
+```go
+func consume(ctx context.Context, ch <-chan Event) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()
+        case event, ok := <-ch:
+            if !ok { return nil }
+            process(event)
+        }
+    }
+}
+```
+
+### Retry with exponential backoff and cap [6]
+```python
+MAX_RETRIES = 5
+
+def fetch_with_retry(url: str) -> Response:
+    for attempt in range(MAX_RETRIES):
+        try:
+            return requests.get(url, timeout=10)
+        except ConnectionError:
+            if attempt == MAX_RETRIES - 1:
+                raise
+            time.sleep(min(2 ** attempt, 30))
+```
+
+## 2. Assertion Density Patterns [1]
+
+### Defensive validation with assertions
+```typescript
+function validateConfig(config: Config): Config {
+  assert(config != null, 'Config must not be null');
+  assert(config.timeout == null || config.timeout > 0, 'Timeout must be positive');
+  assert(config.retries == null || config.retries >= 0, 'Retries must be non-negative');
+  const timeout = config.timeout ?? 5000;
+  const retries = config.retries ?? 3;
+  return { ...config, timeout, retries };
+}
+```
+
+### Post-condition assertions [1]
+```go
+func (q *Queue) Dequeue() (Item, error) {
+    if len(q.items) == 0 {
+        return Item{}, errors.New("dequeue from empty queue")
+    }
+    item := q.items[0]
+    q.items = q.items[1:]
+    assert(q.size > 0, "size invariant violated")
+    q.size--
+    return item, nil
+}
+```
+
+## 3. Allocation Discipline Patterns [1]
+
+### Pooled resources [6]
+```java
+private static final ObjectPool<JsonParser> PARSER_POOL =
+    ObjectPool.create(JsonParser::new, 16);
+
+public void handleRequest(Request req) {
+    JsonParser parser = PARSER_POOL.borrow();
+    try {
+        var result = parser.parse(req.body());
+        respond(result);
+    } finally {
+        PARSER_POOL.release(parser);
+    }
+}
+```
+
+### Pre-sized collections
+```python
+def build_report(items: list[Item]) -> str:
+    parts = [f"{item.name}: {item.value}" for item in items]
+    return "\n".join(parts)  # single allocation for join
+```
+
+## 4. Indirection Limit Patterns [1]
+
+### Flat data structures
+```go
+func update(node *Node) {
+    node.Value = 42  // single dereference
+}
+```
+
+### Direct ownership in Rust
+```rust
+struct Tree {
+    children: Vec<Tree>,  // direct ownership, no double-boxing
+}
+```
+
+### Flat data access
+```typescript
+interface Report {
+  metrics: Record<string, number>;  // single level of indirection
+}
+```
+
+## 5. Metaprogramming Restraint Patterns [1]
+
+### Interface-based dispatch instead of reflection
+```java
+public interface Handler {
+    Object handle(Object... args);
+}
+
+private final Map<String, Handler> handlers = Map.of(
+    "create", this::handleCreate,
+    "delete", this::handleDelete
+);
+
+public Object invoke(String action, Object... args) {
+    Handler h = handlers.get(action);
+    if (h == null) throw new IllegalArgumentException("Unknown: " + action);
+    return h.handle(args);
+}
+```
+
+### Simple derive macros instead of nested macros
+```rust
+#[derive(Debug, Clone)]
+struct Handler {
+    name: String,
+    endpoint: String,
+}
+```

package/src/assets/skills/reliability/references/sources.md

@@ -0,0 +1,27 @@
+# Reliability — Sources
+
+## Primary References
+
+| # | Source | Author(s) | Year | Access | Topics |
+|---|--------|-----------|------|--------|--------|
+| 1 | The Power of Ten — Rules for Developing Safety-Critical Code | Gerard J. Holzmann | 2006 | Free (NASA/JPL) | 10 rules for verifiable, reliable embedded software |
+| 2 | NASA/JPL Coding Standard for the C Programming Language | JPL | 2009 | Free | Institutional coding rules derived from Power of Ten |
+| 3 | MISRA C:2023 — Guidelines for the Use of the C Language in Critical Systems | MISRA | 2023 | Paid | Safety-critical C coding guidelines |
+| 4 | SEI CERT Coding Standards | SEI Carnegie Mellon | 2024 | Free | Language-specific secure and reliable coding rules |
+| 5 | Software Reliability Engineering | John D. Musa | 1998 | Paid | Quantitative reliability measurement and prediction |
+| 6 | Release It! — Design and Deploy Production-Ready Software | Michael T. Nygard | 2018 | Paid | Stability patterns: circuit breakers, bulkheads, timeouts |
+
+## Power of Ten Rules Summary [1]
+
+| Rule | Summary | Devflow Category |
+|------|---------|-----------------|
+| 1 | Restrict to simple control flow — no goto, setjmp, recursion | Bounded Iteration |
+| 2 | Fixed upper bound on all loops | Bounded Iteration |
+| 3 | No dynamic memory allocation after initialization | Allocation Discipline |
+| 4 | No function longer than 60 lines (single printed page) | Complexity (separate skill) |
+| 5 | Minimum two assertions per function on average | Assertion Density |
+| 6 | Declare data at smallest scope | Complexity (separate skill) |
+| 7 | Check return value of every non-void function | Error Handling (engineering rule) |
+| 8 | Limit preprocessor to includes and simple conditionals | Metaprogramming Restraint |
+| 9 | Restrict pointers — no more than one level of dereferencing | Indirection Limits |
+| 10 | Compile with all warnings enabled, zero warnings | Quality rule (zero warnings) |

package/src/assets/skills/reliability/references/violations.md

@@ -0,0 +1,125 @@
+# Reliability — Violation Examples
+
+## 1. Bounded Iteration Violations [1]
+
+### Unbounded pagination
+```typescript
+async function fetchAllPages(url: string) {
+  let page = 1;
+  const results = [];
+  while (true) {                    // no upper bound
+    const data = await fetch(`${url}?page=${page++}`);
+    results.push(...data.items);
+    if (!data.nextPage) break;      // trusts external signal
+  }
+  return results;
+}
+```
+
+### Infinite event loop
+```go
+func consume(ch <-chan Event) {
+    for {                           // no termination condition
+        event := <-ch
+        process(event)
+    }
+}
+```
+
+### Unbounded recursive retry
+```python
+def fetch_with_retry(url: str) -> Response:
+    try:
+        return requests.get(url)
+    except ConnectionError:
+        time.sleep(1)
+        return fetch_with_retry(url)  # unbounded recursion
+```
+
+## 2. Assertion Density Violations [1]
+
+### Zero-assertion validation function
+```typescript
+function validateConfig(config: Config): Config {
+  // 30 lines of transformation with no precondition checks
+  const timeout = config.timeout ?? 5000;
+  const retries = config.retries ?? 3;
+  return { ...config, timeout, retries };
+}
+```
+
+### Missing invariant check after mutation
+```go
+func (q *Queue) Dequeue() Item {
+    item := q.items[0]
+    q.items = q.items[1:]
+    // no assertion that len(q.items) >= 0 or q.size is consistent
+    return item
+}
+```
+
+## 3. Allocation Discipline Violations [1]
+
+### Allocation per request in hot path
+```java
+public void handleRequest(Request req) {
+    byte[] buffer = new byte[1024 * 1024]; // 1MB per request
+    var parser = new JsonParser();          // stateless, could be reused
+    var result = parser.parse(req.body(), buffer);
+    respond(result);
+}
+```
+
+### String concatenation in loop
+```python
+def build_report(items: list[Item]) -> str:
+    result = ""
+    for item in items:
+        result += f"{item.name}: {item.value}\n"  # O(n^2) allocation
+    return result
+```
+
+## 4. Indirection Limit Violations [1]
+
+### Pointer-to-pointer in Go
+```go
+func update(ptr **Node) {
+    (*ptr).Value = 42    // double dereference
+}
+```
+
+### Nested Box in Rust
+```rust
+struct Tree {
+    children: Box<Vec<Box<Tree>>>,  // unnecessary double boxing
+}
+```
+
+### Triple-nested references
+```typescript
+function process(data: Map<string, Map<string, Map<string, number>>>) {
+  // three levels of indirection to reach a value
+}
+```
+
+## 5. Metaprogramming Restraint Violations [1]
+
+### Reflection-heavy dispatch
+```java
+public Object invoke(String methodName, Object... args) throws Exception {
+    Method m = this.getClass().getMethod(methodName,
+        Arrays.stream(args).map(Object::getClass).toArray(Class[]::new));
+    return m.invoke(this, args);  // reflection instead of interface
+}
+```
+
+### Multi-level macro expansion
+```rust
+macro_rules! define_handler {
+    ($name:ident, $($field:ident),*) => {
+        macro_rules! $name {                    // macro defining macro
+            () => { struct Handler { $($field: String),* } }
+        }
+    }
+}
+```