@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/core/shared/skills/do-code-review/languages/ruby.md

@@ -0,0 +1,105 @@
+---
+language: ruby
+extensions: [".rb", ".rake", ".gemspec", ".ru"]
+---
+
+# Ruby — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Ruby-specific rules and idioms.
+
+---
+
+## PR Analyzer — Ruby Risk Signals
+
+- `puts` / `p` / `pp` debug statements left in production code
+- `# rubocop:disable` comments — verify they are justified
+- `eval` / `instance_eval` / `class_eval` with user-controlled input
+- Hardcoded credentials, tokens, or `SECRET_KEY_BASE` in source
+- `binding.pry` / `byebug` / `debugger` left in code
+
+---
+
+## Code Quality — Ruby Checks
+
+- Methods longer than 15 lines — Ruby idioms favor very small methods
+- Classes with more than 10 public methods — possible god object
+- `rescue Exception` — catches `SignalException` and `SystemExit`; use `rescue StandardError` or more specific types
+- `method_missing` implemented without `respond_to_missing?`
+- Deeply nested blocks (>3 levels) — extract to methods
+- String interpolation used where a symbol would suffice (hash keys, etc.)
+
+---
+
+## Security
+
+- Flag `eval` / `instance_eval` with user-controlled strings — remote code execution
+- Flag `system()` / `exec()` / backtick calls with user-controlled input — shell injection
+- Flag `YAML.load` on untrusted data — use `YAML.safe_load`
+- Flag `Marshal.load` on untrusted data — arbitrary code execution
+- Flag raw SQL string interpolation in ActiveRecord — use parameterized queries (`where("name = ?", name)`)
+- Flag `params` passed directly to `redirect_to` without validation — open redirect
+- Flag `render inline:` with user data — XSS via ERB
+- Flag missing `strong_parameters` in Rails controllers — mass assignment vulnerability
+
+---
+
+## Async / Concurrency
+
+- Flag shared mutable state accessed from multiple threads without a `Mutex`
+- Flag `Thread.new` without storing the thread reference — exceptions are silently swallowed
+- Flag `sleep` used as a synchronization mechanism in threaded code
+- Flag `@@class_variables` mutated in multi-threaded contexts — not thread-safe
+- Flag Sidekiq / ActiveJob workers that are not idempotent — jobs can be retried
+
+---
+
+## Resource Management
+
+- Flag `File.open` without a block form — the block form guarantees `close`
+- Flag database connections or HTTP clients not released in `ensure` blocks
+- Flag `ActiveRecord` queries inside loops — N+1 pattern; use `includes` / `preload` / `eager_load`
+- Flag `ObjectSpace` usage in production — memory and performance impact
+
+---
+
+## Exception Handling
+
+- Flag `rescue Exception` — use `rescue StandardError` or a specific exception class
+- Flag empty `rescue` blocks — swallowed errors
+- Flag `rescue` used for control flow (e.g. rescuing `ActiveRecord::RecordNotFound` instead of using `find_by`)
+- Flag re-raising with `raise e` instead of bare `raise` — loses the original backtrace
+- Flag `ensure` blocks that can raise — masks the original exception
+
+---
+
+## Performance
+
+- Flag N+1 ActiveRecord queries — use `includes`, `preload`, or `eager_load`
+- Flag `Array#each` with string concatenation — use `map` + `join`
+- Flag `select` + `map` that could be a single `filter_map`
+- Flag `.count` on an ActiveRecord relation inside a view or loop — triggers a query each time
+- Flag `require` inside a method body — constant overhead on every call
+- Flag `Hash#merge` in a loop — use `merge!` or `each_with_object`
+
+---
+
+## Idioms and Best Practices
+
+### Ruby Style
+- Prefer `map` / `select` / `reject` / `reduce` over manual `each` + accumulator
+- Prefer `&method(:name)` over `{ |x| some_method(x) }` for method reference blocks
+- Prefer `freeze` on string constants to avoid repeated object allocation
+- Use `attr_reader` / `attr_writer` / `attr_accessor` instead of manual getter/setter methods
+- Prefer `Symbol#to_proc` (`&:method_name`) for simple single-method blocks
+
+### Rails-Specific
+- Keep controllers thin — logic belongs in service objects, models, or concerns
+- Use `before_action` for authentication/authorization checks — never inline
+- Prefer `find_by` over `where(...).first` — more intent-revealing
+- Flag `after_commit` callbacks with side effects that should be in a service object
+- Prefer `respond_to` blocks over separate controller actions for format variants
+
+### Modern Ruby (3.x)
+- Prefer pattern matching (`case/in`) for complex data destructuring
+- Use numbered block parameters (`_1`, `_2`) only for very short, obvious blocks
+- Prefer `Data.define` for simple immutable value objects (Ruby 3.2+)

package/core/shared/skills/do-code-review/languages/rust.md

@@ -0,0 +1,99 @@
+---
+language: rust
+extensions: [".rs"]
+---
+
+# Rust — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Rust-specific rules and idioms.
+
+---
+
+## PR Analyzer — Rust Risk Signals
+
+- `unsafe { }` blocks — require explicit justification and sign-off
+- `#[allow(...)]` attributes suppressing lints — verify they are justified
+- `.unwrap()` / `.expect("")` on `Option` or `Result` outside of tests or prototypes
+- Hardcoded credentials or tokens in source
+- `TODO` / `FIXME` comments near `unsafe` or ownership code
+
+---
+
+## Code Quality — Rust Checks
+
+- `.unwrap()` used broadly in production code — prefer `?`, `if let`, or `match`
+- `clone()` called excessively — may indicate ownership design issues
+- `Arc<Mutex<T>>` used where a simpler ownership model would work
+- `Box<dyn Trait>` used where generics (`impl Trait`) would avoid heap allocation
+- `pub` fields on structs that should enforce invariants — use accessor methods
+
+---
+
+## Security
+
+- Flag `unsafe` blocks accessing raw pointers without clear safety invariant documented in a comment
+- Flag `std::mem::transmute` — almost always a logic error or undefined behavior; require strong justification
+- Flag `from_utf8_unchecked` on user-controlled data — use `from_utf8` with error handling
+- Flag `unwrap()` on user-supplied input parsing — panics are a denial-of-service vector in server code
+- Flag hardcoded secrets — use environment variables or a secrets crate
+
+---
+
+## Async / Concurrency
+
+- Flag `std::sync::Mutex` used in async code — use `tokio::sync::Mutex` to avoid blocking the async runtime
+- Flag `.await` inside a `std::sync::MutexGuard` scope — holds the lock across an await point, blocking other tasks
+- Flag `spawn` without storing the `JoinHandle` — panics in the spawned task are silently ignored
+- Flag `Arc<Mutex<T>>` cloned excessively — consider message passing via channels instead
+- Flag blocking I/O calls (`std::fs`, `std::net`) inside async functions — use async equivalents
+
+---
+
+## Resource Management
+
+- Flag manual `drop` called explicitly where the natural scope boundary suffices
+- Flag `Rc<T>` used in multi-threaded code — use `Arc<T>`; the compiler catches this but flag in review for architecture discussion
+- Flag `Vec` or `String` with large pre-allocated capacity never trimmed — call `.shrink_to_fit()` if long-lived
+- Flag `impl Drop` that can panic — causes `abort` during stack unwinding
+
+---
+
+## Exception Handling
+
+- Flag `.unwrap()` in production code outside of tests — use `?` to propagate or handle explicitly
+- Flag `.expect("todo")` or `.expect("")` — messages must explain the invariant that guarantees safety
+- Flag `panic!` used for recoverable errors — use `Result<T, E>`
+- Flag `unwrap_or_default()` where the default silently masks a real error
+- Prefer typed error enums (`thiserror`) over `Box<dyn Error>` for library crates
+- Prefer `anyhow` for application-level error context; `thiserror` for library error types
+
+---
+
+## Performance
+
+- Flag `.clone()` on large types in hot paths — review whether a reference or `Cow<T>` would work
+- Flag `format!` used only to create a `String` from a literal — use `.to_string()` or `String::from`
+- Flag `collect::<Vec<_>>()` followed immediately by `.iter()` — chain iterators instead
+- Flag `Box<T>` for small types where stack allocation is fine
+- Flag `Mutex` contention on a hot path — consider `RwLock` for read-heavy workloads or sharding
+
+---
+
+## Idioms and Best Practices
+
+### Ownership
+- Prefer borrowing (`&T`, `&mut T`) over cloning wherever the lifetime allows
+- Use `Cow<'_, str>` for functions that sometimes need to own and sometimes borrow
+- Prefer `impl Trait` in function signatures over `Box<dyn Trait>` for static dispatch
+
+### Error Handling
+- Use `?` operator to propagate errors — avoid manual `match Err(e) => return Err(e)`
+- Define domain error types with `thiserror` in libraries; use `anyhow` in binaries
+- Never use `.unwrap()` in library code — it panics the caller's thread
+
+### Modern Rust
+- Prefer `if let` / `while let` for single-variant matches over full `match`
+- Prefer `?` over `unwrap` everywhere errors are recoverable
+- Use `#[derive(Debug, Clone, PartialEq)]` consistently on data types
+- Prefer `iter()` chains over manual loops — they compose and optimize well
+- Use `clippy` and treat its lints as required — flag any `#[allow(clippy::...)]` in review

package/core/shared/skills/do-code-review/languages/shell.md

@@ -0,0 +1,90 @@
+---
+language: shell
+extensions: [".sh", ".bash", ".zsh"]
+---
+
+# Shell — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only
+shell-specific rules and idioms.
+
+Shell sits in `languages/` rather than `content-types/` because it is executable code with real
+control flow: functions, branches, loops, and a complexity reading that means something. Its
+failure modes are its own, though — almost every serious shell bug is a quoting bug, an unchecked
+exit status, or a command that ran in the wrong directory.
+
+---
+
+## PR Analyzer — Shell Risk Signals
+
+- No `set -euo pipefail` (or equivalent) near the top of an executable script
+- `rm -rf` with any variable in the path
+- `eval`, or a command assembled by string concatenation
+- `curl ... | bash`, or any pipe from the network into an interpreter
+- `sudo` inside a script that is not documented as requiring it
+- A `trap` that is registered but cleans up nothing, or is absent where a temp dir is created
+
+## Code Quality — Shell Checks
+
+- **Unquoted expansion** — `$VAR` rather than `"$VAR"` in any command touching a path. A value with
+  a space becomes two arguments; a value with `*` becomes whatever the glob matched. This is the
+  single most common real shell defect and the analyser flags it for path-acting commands.
+- **Unchecked `cd`** — `cd "$dir"` without `|| exit` and without `set -e` leaves every subsequent
+  line running in the previous directory. The commands still "succeed", against the wrong tree.
+- **Unchecked command substitution** — `x=$(cmd)` swallows `cmd`'s exit status unless `set -e` and
+  `pipefail` are both in force.
+- **`[` vs `[[`** — prefer `[[ ]]` in bash: it does not word-split, so an empty variable does not
+  turn a comparison into a syntax error.
+- **Long functions** — the universal threshold applies; a shell function past it is usually several
+  scripts that never got separated.
+
+## Security
+
+- Never interpolate untrusted input into a command string; pass it as an argument.
+- `eval` is a finding unless the review can name why nothing else works.
+- Secrets passed as command-line arguments are visible in `ps`; prefer an environment variable read
+  from a file, or stdin.
+- A temp file created without `mktemp` is a predictable path, which is a symlink attack.
+- `IFS` changed without being restored affects every later word-split in the script.
+
+## Async / Concurrency
+
+- A backgrounded job (`&`) whose exit status is never collected by `wait` fails silently.
+- `nohup ... &` detaches deliberately; the review should confirm the output redirection is explicit,
+  since an inherited stdin or stdout fd can hold a pipe open and hang the caller.
+- Parallel writes to one file from backgrounded jobs interleave; append-with-`>>` is not atomic
+  above the pipe buffer size.
+
+## Resource Management
+
+- Every `mktemp` needs a matching `trap ... EXIT` that removes it, including on the error paths.
+- A `trap` registered after the resource is created leaves a window where a signal leaks it.
+- File descriptors opened with `exec 3<` are closed with `exec 3<&-`, not by falling off the end.
+
+## Exception Handling
+
+- Shell has no exceptions; `set -e` plus explicit `|| { ...; exit 1; }` is the mechanism.
+- `set -e` does not apply inside a command substitution, a condition, or the left side of `&&` —
+  a review that assumes it does will pass code that silently continues.
+- An error message must go to stderr (`>&2`), or a caller capturing stdout will absorb it as data.
+- A non-zero exit that is expected and handled should say so in a comment; a reader cannot tell an
+  ignored failure from a tolerated one.
+
+## Performance
+
+- A loop calling an external binary per line is the usual cause of a slow script; `awk`, `sed` or a
+  single `xargs` does the same work in one process.
+- `$(cat file)` reads the whole file into memory; `< file` in a redirect does not.
+- Subshells `( )` fork; braces `{ }` do not. Reaching for the first out of habit costs a process per
+  iteration.
+
+## Idioms and Best Practices
+
+- `#!/usr/bin/env bash` rather than a hardcoded interpreter path.
+- `set -euo pipefail` at the top of anything executable, with a comment where one of the three is
+  deliberately omitted (a hook that must fail open, for example — see this repository's own hooks).
+- Quote every expansion by default; make the unquoted ones the exception that carries a comment.
+- `local` on every variable inside a function — shell variables are global otherwise.
+- `readonly` for constants, so a later assignment is an error rather than a surprise.
+- `shellcheck` catches most of the above; this file exists because the bundled analyser must work
+  without it (see the skill's no-external-dependency constraint).

package/core/shared/skills/do-code-review/languages/swift.md

@@ -0,0 +1,88 @@
+---
+language: swift
+extensions: [".swift"]
+---
+
+# Swift — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Swift-specific rules and idioms.
+
+---
+
+## PR Analyzer — Swift Risk Signals
+
+- `print()` statements left in production code
+- Force unwrap (`!`) on optionals outside of tests or justified init
+- Force cast (`as!`) without a safe fallback
+- Hardcoded credentials or API keys in source
+
+---
+
+## Code Quality — Swift Checks
+
+- Force unwrap (`!`) used broadly — prefer `guard let` or `if let`
+- `try!` used outside of guaranteed-safe contexts
+- Retain cycles in closures — missing `[weak self]` or `[unowned self]`
+- `@objc` / `dynamic` used without an Objective-C interop reason
+
+---
+
+## Security
+
+- Flag credentials stored in `UserDefaults` — require Keychain
+- Flag `URLSession` requests over plain HTTP in production
+- Flag `WKWebView` loading arbitrary user-supplied URLs without validation
+
+---
+
+## Async / Concurrency
+
+- Flag `DispatchQueue.main.sync` called from the main thread — deadlock
+- Flag `@escaping` closures capturing `self` strongly in reference cycles — use `[weak self]`
+- Flag mixing `async/await` and `DispatchQueue` for the same operation without clear reasoning
+- Flag `Task { }` (unstructured) where a structured `async let` or `TaskGroup` would maintain structure
+- Flag data races — shared mutable state accessed from multiple tasks without an actor
+
+---
+
+## Resource Management
+
+- Flag `URLSessionDataTask` started with no cancellation handle stored — cannot be cancelled if the view disappears
+- Flag `NotificationCenter` observers added without a corresponding `removeObserver` — memory leak
+- Flag `CLLocationManager` / `AVCaptureSession` not stopped when the owning view controller is dismissed
+
+---
+
+## Exception Handling
+
+- Flag `try!` outside of guaranteed-safe contexts (test fixtures, constants) — crashes on failure
+- Flag `try?` discarding errors where the failure mode matters to the caller
+- Flag error types conforming to `Error` with no associated values or message — makes debugging hard
+- Flag throwing functions calling `fatalError()` as a fallback — choose one error strategy
+
+---
+
+## Performance
+
+- Flag `UIImage(named:)` called repeatedly for the same asset without caching
+- Flag synchronous network calls on the main thread
+- Flag `Array` used for frequent membership tests — prefer `Set`
+- Flag `String` interpolation inside tight loops where a pre-built string would avoid allocations
+
+---
+
+## Idioms and Best Practices
+
+### Optionals
+- Prefer `guard let` for early exit; `if let` for local scope
+- Prefer optional chaining (`?.`) over force unwrap
+- Flag implicitly unwrapped optionals (`var x: String!`) outside of `@IBOutlet`
+
+### Memory Management
+- Flag closures capturing `self` strongly in reference cycles — use `[weak self]`
+- Prefer `struct` over `class` for value semantics unless identity or inheritance is needed
+- Use `unowned` only when the lifetime is guaranteed — otherwise `weak`
+
+### Concurrency (Swift 5.5+)
+- Prefer `async/await` over completion handlers in new code
+- Flag `DispatchQueue.main.async` where `@MainActor` or `await MainActor.run` is more appropriate

package/core/shared/skills/do-code-review/languages/typescript.md

@@ -0,0 +1,97 @@
+---
+language: typescript
+extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs"]
+---
+
+# TypeScript / JavaScript — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only TypeScript/JavaScript-specific rules and idioms.
+
+---
+
+## PR Analyzer — TypeScript / JavaScript Risk Signals
+
+- `console.log` / `debugger` statements left in production code
+- `// eslint-disable` comments — verify they are justified
+- `any` type annotations — require explicit justification
+- `@ts-ignore` / `@ts-expect-error` — verify they are justified
+- `eval()` with any dynamic or user-controlled input
+- Hardcoded API keys or tokens in source
+
+---
+
+## Code Quality — TypeScript / JavaScript Checks
+
+- `any` used broadly instead of proper typing
+- Non-null assertion (`!`) used without justification
+- `var` declarations — prefer `const` / `let`
+- Missing `await` on async function calls
+- Floating promises (no `.catch()` and no `await`)
+- `==` used instead of `===`
+
+---
+
+## Security
+
+- Flag `innerHTML`, `outerHTML`, `document.write()` with user-controlled data — use `textContent` or a sanitizer
+- Flag `dangerouslySetInnerHTML` in React without a sanitizer
+- Flag `eval()` / `new Function()` with dynamic input
+- Flag JWT decoded without signature verification
+- Flag missing `httpOnly` / `secure` flags on cookies
+
+---
+
+## Async / Promises
+
+- Flag floating promises — async calls not `await`-ed and without `.catch()`
+- Flag `Promise.all()` where `Promise.allSettled()` is safer (one failure should not cancel siblings)
+- Flag `async` functions inside `forEach` — `forEach` does not await; use `for...of` or `Promise.all()`
+- Flag unhandled promise rejection (no global `unhandledRejection` handler in Node.js services)
+
+---
+
+## Resource Management
+
+- Flag `fs.createReadStream` / `fs.createWriteStream` with no `close` or `destroy` on error
+- Flag `EventEmitter` listeners added in a loop without removal — memory leak
+- Flag `setInterval` / `setTimeout` handles not cleared when the owning component unmounts or exits
+- Flag database clients / pools not released after use in Node.js
+
+---
+
+## Exception Handling
+
+- Flag `catch (e) {}` (empty catch) — swallowed error
+- Flag `catch (e)` where `e` is used as `any` without narrowing — type the error properly
+- Flag `Promise` rejection not handled — `.catch()` or `try/await/catch` required
+- Flag re-throwing a new `Error` without wrapping the original — loses stack context
+- Use `Error` subclasses for domain errors rather than plain strings or object literals
+
+---
+
+## Performance
+
+- Flag `Array.prototype.find` / `filter` / `map` chained multiple times over the same array — combine into one pass
+- Flag DOM queries (`document.querySelector`) inside loops — cache the result
+- Flag `JSON.parse` / `JSON.stringify` in a hot path on large objects — consider streaming or partial parsing
+- Flag `async` functions called sequentially in a loop where `Promise.all()` would parallelize them
+
+---
+
+## Idioms and Best Practices
+
+### Type Safety (TypeScript)
+- Prefer `unknown` over `any` for truly unknown values — forces a type guard before use
+- Prefer type narrowing (`typeof`, `instanceof`, discriminated unions) over casting
+- Enable `strict` mode in `tsconfig.json`
+- Prefer `interface` for object shapes that may be extended; `type` for unions and aliases
+
+### Modern JavaScript / TypeScript
+- Prefer `const` by default; `let` only when reassignment is needed
+- Prefer optional chaining (`?.`) and nullish coalescing (`??`) over manual null guards
+- Prefer `structuredClone()` over manual deep-copy patterns
+- Prefer named exports over default exports for better refactoring support
+
+### Null / Undefined Safety
+- Distinguish between `null` (intentional absence) and `undefined` (not set) — be consistent
+- Flag `== null` checks that accidentally include `undefined` when only one is intended

package/core/shared/skills/do-code-review/review-policy.json

@@ -0,0 +1,47 @@
+{
+  "description": "Review policy DoFlow ships. The analyzer resolves three tiers, lowest precedence first: its built-in literal, this file, then agent-docs/review-policy.json in the repository under review. A project overrides individual values by declaring only those values in its own file; everything it omits resolves from here. Documentation must name this file rather than restate any value in it, and a guard in the default test suite fails when a shipped document carries a number declared here.",
+  "thresholds": {
+    "long_function_lines": 50,
+    "too_many_parameters": 5,
+    "high_complexity": 10,
+    "god_class_methods": 20,
+    "max_imports": 15,
+    "max_declarative_depth": 8
+  },
+  "thresholdLabels": {
+    "long_function_lines": "Long function",
+    "too_many_parameters": "Too many params",
+    "high_complexity": "High complexity",
+    "god_class_methods": "God class",
+    "max_imports": "Too many imports",
+    "max_declarative_depth": "Nesting depth"
+  },
+  "severities": [
+    "low",
+    "medium",
+    "high"
+  ],
+  "verdictBands": [
+    {
+      "verdict": "Approve",
+      "minScore": 90,
+      "maxHighFindings": 0
+    },
+    {
+      "verdict": "Approve with suggestions",
+      "minScore": 75,
+      "maxHighFindings": 2
+    },
+    {
+      "verdict": "Request changes",
+      "minScore": 50,
+      "maxHighFindings": null
+    },
+    {
+      "verdict": "Block",
+      "minScore": 0,
+      "maxHighFindings": null
+    }
+  ],
+  "exclusions": []
+}

package/core/shared/skills/do-code-review/rules/universal.md

@@ -0,0 +1,49 @@
+# Universal Rules — All Languages
+
+These rules apply regardless of language. Load this file for every review, alongside the relevant `languages/*.md` file.
+
+---
+
+## Security
+
+- Flag any string interpolation or concatenation used to build SQL, shell, or LDAP queries — require parameterized queries or a safe API
+- Flag hardcoded credentials, API keys, tokens, or secrets anywhere in source — require environment variables or a secrets manager
+- Flag user-controlled input passed to file system, process execution, or URL redirect APIs without validation
+- Flag overly broad CORS or CSP policies
+
+---
+
+## Async / Concurrency
+
+- Flag shared mutable state accessed from multiple threads/coroutines/tasks without synchronization
+- Flag fire-and-forget async operations with no error handling path
+- Flag timeouts missing on any network or I/O call
+- Flag unbounded queues or thread pools with no backpressure mechanism
+
+---
+
+## Resource Management
+
+- Flag any resource (file, socket, DB connection, HTTP connection) acquired without a guaranteed release path
+- Flag connection pools not returned to the pool on all code paths (including exceptions)
+- Flag unbounded collections that grow without eviction — potential memory leak
+- Flag resources held open longer than the operation they serve
+
+---
+
+## Exception Handling
+
+- Flag empty catch/except blocks — swallowed exceptions hide bugs silently
+- Flag catching the broadest possible exception type (`Exception`, `Throwable`, `error`) where a specific type is appropriate
+- Flag exceptions used for normal control flow (signaling "not found", etc.) — use return values or `Optional`
+- Flag error context lost when re-throwing — always wrap with the original cause
+
+---
+
+## Performance
+
+- Flag N+1 query patterns — loading a collection then querying for each item individually
+- Flag unbounded queries or API calls with no pagination or limit
+- Flag synchronous I/O on a thread or event loop that serves concurrent requests
+- Flag large objects serialized/deserialized repeatedly when they could be cached
+- Flag string concatenation in tight loops — use a builder or join