devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/review-methodology/references/violations.md

@@ -0,0 +1,125 @@
+# Review Methodology Violations
+
+Common anti-patterns that undermine effective code reviews.
+
+---
+
+## Review Process Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Blocking for pre-existing issues | Unfair to author | Only flag issues in changed code |
+| Missing severity classification | Unclear priority | Use CRITICAL/HIGH/MEDIUM/LOW |
+| No file:line references | Hard to locate | Always include specific locations |
+| Vague feedback | Not actionable | Provide concrete fixes |
+| Mixing concerns | Confusing review | Separate by category |
+| Opinion as requirement | Overreach | Distinguish style from correctness |
+
+---
+
+## Diff Analysis Violations
+
+### Incorrect Base Branch Detection
+
+```bash
+# VIOLATION: Hardcoding base branch
+BASE_BRANCH="main"  # Fails if repo uses master or develop
+
+# VIOLATION: Not verifying branch exists
+git diff main...HEAD  # Errors if main doesn't exist
+```
+
+### Missing Change Context
+
+```bash
+# VIOLATION: Getting all files instead of changed files
+git ls-files  # Wrong - includes unchanged files
+
+# VIOLATION: Missing line-level precision
+git diff --name-only  # Only file names, no line numbers
+```
+
+---
+
+## PR Comment Violations
+
+### Commenting on Wrong Lines
+
+```bash
+# VIOLATION: Commenting without checking if file is in diff
+gh api "repos/${REPO}/pulls/${PR_NUMBER}/comments" \
+    -f path="$FILE" \
+    -f line="$LINE"  # May fail if file not in PR
+
+# VIOLATION: No rate limiting
+for issue in "${ISSUES[@]}"; do
+    create_pr_comment "$issue"  # Will hit API rate limits
+done
+```
+
+### Wrong Comment Scope
+
+```bash
+# VIOLATION: Commenting on pre-existing issues
+# Category 3 issues should NOT get PR comments
+create_pr_comment "file.ts" "456" "Pre-existing bug"  # Wrong!
+
+# VIOLATION: Missing severity indicator
+create_pr_comment "file.ts" "123" "This is a problem"  # No severity
+```
+
+---
+
+## Report Violations
+
+### Missing Structure
+
+```markdown
+# VIOLATION: Flat list without categories
+
+- Bug in file.ts:123
+- Security issue in auth.ts:45
+- Style problem in utils.ts:89
+```
+
+### Missing Context
+
+```markdown
+# VIOLATION: Issue without remediation
+
+**Issue**: SQL injection in query.ts:34
+<!-- No fix provided, no severity, no impact -->
+```
+
+### Incorrect File Naming
+
+```bash
+# VIOLATION: Non-standard naming
+REPORT_FILE="review.md"  # No timestamp, no branch
+
+# VIOLATION: Wrong directory
+REPORT_FILE="./reviews/report.md"  # Should be .devflow/docs/reviews/
+```
+
+---
+
+## Detection Patterns
+
+Use these to find violations in review code:
+
+```bash
+# Find hardcoded base branches
+grep -r 'BASE_BRANCH="main"' --include="*.sh"
+
+# Find missing rate limiting
+grep -r 'gh api.*comments' --include="*.sh" | grep -v 'sleep'
+
+# Find missing severity classifications
+grep -r 'create_pr_comment' --include="*.sh" | grep -v 'CRITICAL\|HIGH\|MEDIUM\|LOW'
+```
+
+---
+
+## Quick Reference
+
+See [report-template.md](report-template.md) for proper review format.

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

@@ -0,0 +1,148 @@
+---
+name: rust
+description: This skill should be used when the user works with Rust files (.rs), asks about "ownership", "borrowing", "lifetimes", "Result/Option", "traits", or discusses memory safety and type-driven design. Provides patterns for ownership, error handling, type system usage, and safe concurrency.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.rs"
+  exclude:
+    - "**/target/**"
+---
+
+# Rust Patterns
+
+Reference for Rust-specific patterns, ownership model, and type-driven design.
+
+## Iron Law
+
+> **MAKE ILLEGAL STATES UNREPRESENTABLE** [15][2, C-VALIDATE]
+>
+> Encode invariants in the type system. If a function can fail, return `Result`. If a value
+> might be absent, return `Option`. If a state transition is invalid, make it uncompilable.
+> Runtime checks are a fallback, not a strategy.
+
+## When This Skill Activates
+
+- Working with Rust codebases
+- Designing type-safe APIs
+- Managing ownership and borrowing
+- Implementing error handling
+- Writing concurrent code
+
+---
+
+## Ownership & Borrowing [1, Ch.4][11]
+
+Prefer borrowing over cloning — accept `&str` not `String`, `&[T]` not `&Vec<T>` [2, C-BORROW].
+The borrow checker enforces the Stacked Borrows aliasing model at compile time [6][11].
+Lifetime annotations required when elision rules can't resolve ambiguity [1, Ch.10].
+
+```rust
+// BAD: fn process(data: String) — takes ownership unnecessarily
+fn process(data: &str) -> usize { data.len() } // GOOD: borrow [2, C-BORROW]
+```
+
+See `references/ownership.md` for elision rules, interior mutability, Cow, and Pin.
+
+---
+
+## Error Handling [8][9][16]
+
+Use `thiserror` for libraries (typed, matchable variants); `anyhow` for applications
+(ergonomic propagation). Never use `Box<dyn Error>` in library APIs [8][16].
+
+```rust
+#[derive(thiserror::Error, Debug)]
+pub enum AppError {
+    #[error("IO error reading {path}")]
+    Io { path: String, #[source] source: io::Error },
+    #[error("{entity} with id {id} not found")]
+    NotFound { entity: String, id: String },
+}
+// ? operator propagates with source context [1, Ch.9]
+fn read_config(path: &str) -> Result<Config, AppError> {
+    let raw = fs::read_to_string(path).map_err(|e| AppError::Io { path: path.into(), source: e })?;
+    toml::from_str(&raw).map_err(|e| AppError::Parse { source: e })
+}
+```
+
+---
+
+## Type System
+
+### Newtype Pattern [2, C-NEWTYPE][15]
+
+```rust
+struct UserId(String);   struct OrderId(String);
+// Can't accidentally swap — compiler enforces [15]
+fn get_order(user_id: &UserId, order_id: &OrderId) -> Result<Order, AppError> { todo!() }
+```
+
+### Enums for State Machines [4][15][27]
+
+Each state carries only its relevant data; invalid transitions don't compile [15][27]:
+
+```rust
+enum Connection { Disconnected, Connecting { attempt: u32 }, Connected { session: Session } }
+```
+
+### Builder Pattern [2, C-BUILDER][4]
+
+```rust
+impl ServerBuilder {
+    pub fn new() -> Self { Self { port: 8080, host: "localhost".into() } }
+    pub fn port(mut self, p: u16) -> Self { self.port = p; self }
+    pub fn build(self) -> Server { Server { port: self.port, host: self.host } }
+}
+```
+
+---
+
+## Concurrency [1, Ch.16][29]
+
+Prefer channels over shared mutable state. `Send`/`Sync` traits prevent data races at
+compile time — enforced by RustBelt's formal model [6][29]. Use `tokio::fs` or
+`spawn_blocking` in async contexts — never `std::fs` (blocks the runtime) [13].
+
+```rust
+// mpsc channels over Mutex<Vec> for communication [1, Ch.16]
+let (tx, mut rx) = tokio::sync::mpsc::channel::<Work>(100);
+```
+
+---
+
+## Anti-Patterns [7][8][2]
+
+| Bad | Good | Source |
+|-----|------|--------|
+| `.unwrap()` in library | `?` or `.ok_or()` | [8] |
+| `.clone()` to satisfy borrow checker | Restructure ownership | [2, C-BORROW] |
+| `HashMap<String, String>` | Typed structs and enums | [2, C-NEWTYPE] |
+| `let _ = write(...)` | Handle or propagate | [7] |
+| `std::fs::` in async fn | `tokio::fs::` or `spawn_blocking` | [13] |
+
+---
+
+## Extended References
+
+- `references/sources.md` — Full bibliography (~30 sources with access links)
+- `references/violations.md` — Violation patterns with citations
+- `references/patterns.md` — Extended patterns with citations
+- `references/ownership.md` — Lifetimes, interior mutability, Stacked Borrows, Pin
+- `references/detection.md` — Clippy and grep patterns for automated detection
+
+---
+
+## Checklist
+
+- [ ] No `.unwrap()` in library/application code (ok in tests) [8]
+- [ ] `thiserror` for library errors; `anyhow` for application code [9][16]
+- [ ] `?` operator for error propagation [1, Ch.9]
+- [ ] Borrow instead of clone where possible [2, C-BORROW]
+- [ ] Newtype pattern for type-safe IDs [2, C-NEWTYPE]
+- [ ] Enums for state machines [4][15]
+- [ ] `#[must_use]` on Result-returning functions [7]
+- [ ] No `unsafe` without `// SAFETY:` comment [3][11]
+- [ ] Clippy clean (`cargo clippy -- -D warnings`) [7]
+- [ ] No blocking calls in async context [13]

package/src/assets/skills/rust/references/ownership.md

@@ -0,0 +1,278 @@
+# Rust Ownership Deep Dive
+
+Advanced ownership patterns, lifetime elision, interior mutability, and pinning.
+Citations reference `sources.md`.
+
+## Lifetime Elision Rules [1, Ch.10]
+
+The compiler applies three rules to infer lifetimes. When they don't resolve, annotate manually.
+These rules are part of the formal type system verified by RustBelt [6].
+
+### Rule 1: Each Reference Parameter Gets Its Own Lifetime [1, Ch.10]
+
+```rust
+// Compiler sees: fn first(s: &str) -> &str
+// Compiler infers: fn first<'a>(s: &'a str) -> &'a str [1, Ch.10]
+fn first(s: &str) -> &str {
+    &s[..1]
+}
+```
+
+### Rule 2: Single Input Lifetime Applies to All Outputs [1, Ch.10]
+
+```rust
+// One input reference — output borrows from it [1, Ch.10]
+fn trim(s: &str) -> &str {
+    s.trim()
+}
+```
+
+### Rule 3: &self Lifetime Applies to All Outputs in Methods [1, Ch.10]
+
+```rust
+impl Config {
+    // &self lifetime flows to return — elision rule 3 [1, Ch.10]
+    fn database_url(&self) -> &str {
+        &self.db_url
+    }
+}
+```
+
+### When Elision Fails [1, Ch.10]
+
+```rust
+// Two input lifetimes — compiler can't decide which output borrows from [1, Ch.10]
+// Must annotate: output borrows from `a`, not `b`
+fn longest<'a>(a: &'a str, b: &str) -> &'a str {
+    if a.len() >= b.len() { a } else { a }
+}
+```
+
+---
+
+## Aliasing and the Stacked Borrows Model [11][3]
+
+Rust's borrow checker enforces that at any point in time, you have either:
+- Any number of immutable references (`&T`), OR
+- Exactly one mutable reference (`&mut T`)
+
+The **Stacked Borrows** model [11] formalizes this as a stack of "tags" tracking which
+borrow is currently active. Any access through an expired tag is undefined behavior — even
+in `unsafe` code. This is the theoretical foundation for why Rust code can be optimized
+aggressively without data races [6][11].
+
+```rust
+// CORRECT: Immutable borrows can coexist [1, Ch.4]
+let s = String::from("hello");
+let r1 = &s;
+let r2 = &s;
+println!("{} {}", r1, r2); // Both valid — multiple shared refs [11]
+
+// CORRECT: Mutable borrow is exclusive [1, Ch.4]
+let mut s = String::from("hello");
+let r = &mut s;
+r.push_str(", world"); // Only r can access s [11]
+// s is accessible again after r's scope ends
+```
+
+### Unsafe and Stacked Borrows [11][3]
+
+When writing `unsafe` code that creates raw pointers, the Stacked Borrows invariant
+must still hold. Violations cause undefined behavior that Miri can detect:
+
+```rust
+// SAFETY: We derive one mutable pointer and do not alias it.
+// Stacked Borrows: the raw pointer is derived from a unique mutable reference,
+// no other pointer accesses this memory during the operation. [11][3]
+unsafe fn fill_bytes(dest: *mut u8, len: usize) {
+    for i in 0..len {
+        // SAFETY: caller guarantees dest points to len valid bytes.
+        *dest.add(i) = 0;
+    }
+}
+```
+
+---
+
+## Interior Mutability [1, Ch.15][14]
+
+Mutate data behind a shared reference when ownership rules are too strict.
+Each type trades compile-time safety for runtime checking at different granularities [1, Ch.15].
+
+### Cell — Copy Types Only [1, Ch.15]
+
+```rust
+use std::cell::Cell;
+
+struct Counter {
+    count: Cell<u32>, // Mutate through &self — no runtime borrow check [1, Ch.15]
+}
+
+impl Counter {
+    fn increment(&self) {
+        self.count.set(self.count.get() + 1);
+    }
+}
+```
+
+### RefCell — Runtime Borrow Checking [1, Ch.15]
+
+```rust
+use std::cell::RefCell;
+
+struct Cache {
+    data: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get_or_insert(&self, key: &str, value: &str) -> String {
+        let mut data = self.data.borrow_mut(); // Panics if already borrowed [1, Ch.15]
+        data.entry(key.to_string())
+            .or_insert_with(|| value.to_string())
+            .clone()
+    }
+}
+```
+
+### Mutex — Thread-Safe Interior Mutability [1, Ch.16][29]
+
+```rust
+use std::sync::Mutex;
+
+struct SharedState {
+    data: Mutex<Vec<String>>,
+}
+
+impl SharedState {
+    fn push(&self, item: String) -> Result<(), AppError> {
+        let mut data = self.data.lock()
+            .map_err(|_| AppError::LockPoisoned)?; // Handle poison explicitly [1, Ch.16]
+        data.push(item);
+        Ok(())
+    }
+}
+```
+
+### Decision Guide [1, Ch.15][29]
+
+| Type | Thread-Safe | Cost | Use Case |
+|------|-------------|------|----------|
+| `Cell<T>` | No | Zero | Copy types, single-threaded |
+| `RefCell<T>` | No | Runtime borrow check | Non-Copy, single-threaded [1, Ch.15] |
+| `Mutex<T>` | Yes | Lock overhead | Multi-threaded mutation [29] |
+| `RwLock<T>` | Yes | Lock overhead | Multi-threaded, read-heavy [29] |
+| `Atomic*` | Yes | Hardware atomic | Counters, flags [29] |
+
+---
+
+## Cow — Clone on Write [2, C-BORROW][5, Item 10]
+
+Defer cloning until mutation is actually needed. Ideal for functions that return
+borrowed data in the common case and owned data in the exceptional case [2, C-BORROW].
+
+```rust
+use std::borrow::Cow;
+
+// Returns borrowed if no processing needed, owned if modified [2, C-BORROW]
+fn normalize_path(path: &str) -> Cow<'_, str> {
+    if path.contains("//") {
+        Cow::Owned(path.replace("//", "/"))
+    } else {
+        Cow::Borrowed(path)
+    }
+}
+
+// Accept Cow for flexible ownership — caller decides allocation [2, C-BORROW]
+pub fn log_message(msg: Cow<'_, str>) {
+    eprintln!("[LOG] {}", msg);
+}
+
+log_message(Cow::Borrowed("static message")); // Zero allocation
+log_message(Cow::Owned(format!("dynamic: {}", value))); // No extra clone
+```
+
+---
+
+## Pin for Async and Self-Referential Types [1, Ch.17][13]
+
+### Why Pin Exists [13]
+
+Self-referential structs break if moved in memory. `Pin<P>` guarantees the pointed-to
+value won't move, enabling async futures that hold references to their own stack frames [13].
+
+```rust
+use std::pin::Pin;
+use std::future::Future;
+
+// Async functions return self-referential futures — Pin ensures stability [13]
+fn fetch_data(url: &str) -> Pin<Box<dyn Future<Output = Result<Data, Error>> + '_>> {
+    Box::pin(async move {
+        let response = reqwest::get(url).await?;
+        let data = response.json::<Data>().await?;
+        Ok(data)
+    })
+}
+```
+
+### Pin in Practice [13]
+
+```rust
+use tokio::pin;
+
+async fn process_stream(stream: impl Stream<Item = Data>) {
+    // pin! macro pins the stream to the stack — safe without Box [13]
+    pin!(stream);
+
+    while let Some(item) = stream.next().await {
+        handle(item).await;
+    }
+}
+```
+
+### When You Need Pin [13]
+
+| Scenario | Need Pin? |
+|----------|-----------|
+| Returning `async` blocks as trait objects | Yes |
+| Implementing `Future` manually | Yes |
+| Using `tokio::select!` on futures | Yes (automatically handled) |
+| Normal async/await | No (compiler handles it) |
+| Storing futures in collections | Yes (`Pin<Box<dyn Future>>`) |
+
+---
+
+## Ownership Transfer Patterns [1, Ch.4][5]
+
+### Take Pattern — Move Out of Option [4]
+
+```rust
+struct Connection {
+    session: Option<Session>,
+}
+
+impl Connection {
+    fn close(&mut self) -> Option<Session> {
+        self.session.take() // Moves out, leaves None — no partial move [4]
+    }
+}
+```
+
+### Swap Pattern — Replace In Place [4]
+
+```rust
+use std::mem;
+
+fn rotate_buffer(current: &mut Vec<u8>, new_data: Vec<u8>) -> Vec<u8> {
+    mem::replace(current, new_data) // Returns old, installs new — no clone [4]
+}
+```
+
+### Entry Pattern — Conditional Insertion [1, Ch.8]
+
+```rust
+use std::collections::HashMap;
+
+fn get_or_create(map: &mut HashMap<String, Vec<Item>>, key: &str) -> &mut Vec<Item> {
+    map.entry(key.to_string()).or_insert_with(Vec::new) // Single lookup, no double-insert [1, Ch.8]
+}
+```