neo-skill 0.1.23 → 0.1.25

package/.shared/review-gate/README.md

@@ -0,0 +1,237 @@
+# .shared/review-gate
+
+Production-grade architecture/code anti-corruption review skill with modular, data-driven, searchable system.
+
+## Overview
+
+review-gate is NOT hard-gate. It focuses on:
+- Architecture decisions and module boundaries
+- Dependency direction and layer violations
+- Side-effect isolation and testability
+- Long-term maintainability and "slow decay" prevention
+
+**Evidence-first**: Every finding is backed by concrete evidence (files, diff hunks, dependency traces).
+
+## Architecture
+
+### 3-Layer Design (aligned with skill-creator conventions)
+
+1. **Data Layer (Domains Index)**
+   - Split knowledge into 14 domains: layer/dep/api/pure/complex/error/obs/type/async/ui/perf/sec/doc/test
+   - Each domain contains: checks.csv, recipes.md, anti_patterns.md, hardgate_candidates.csv
+
+2. **Reasoning Layer (Routing & Prioritization)**
+   - review-reasoning.csv maps signals → domains/checks/recipes with weights
+   - Supports layered overrides (paths > packages > stacks > MASTER)
+
+3. **Runtime Layer (Analyzers + Router + Composer)**
+   - Signal analyzers: diff, dependency graph, layer classification, API surface, side-effects, complexity
+   - Router: loads overrides + reasoning rules, selects checks
+   - Composer: generates findings (JSON + Markdown) + reports
+
+## Prerequisites
+
+- Python 3.8+
+- Git (for diff analysis)
+- Node.js/TypeScript project (for dependency graph analysis)
+
+## Usage
+
+### Basic Review
+
+```bash
+python3 .shared/review-gate/scripts/review.py --base-branch main
+```
+
+### With Test Enforcement
+
+```bash
+python3 .shared/review-gate/scripts/review.py --ensure-tests-pass --base-branch main
+```
+
+### Focused Domain Search
+
+```bash
+python3 .shared/review-gate/scripts/review.py --domain layer --max-results 10
+```
+
+### Stack-Specific Review
+
+```bash
+python3 .shared/review-gate/scripts/review.py --stack nextjs --base-branch main
+```
+
+### Persist Override Rules
+
+```bash
+python3 .shared/review-gate/scripts/review.py --persist path --path src/domain/user
+```
+
+## Workflow
+
+1. Creates branch: `review-gate/<YYYYMMDD>-<topic>-<ref>`
+2. (Optional) Runs existing tests baseline
+3. Extracts PR diff changeset
+4. Builds impacted dependency subgraph
+5. Generates signals (layer/dep/api/pure/complex/etc.)
+6. Router selects & prioritizes checks
+7. Composer generates findings + report
+8. (Optional) Applies minimal fixes for blockers
+9. (Optional) Reruns tests to ensure green
+10. Outputs final report (Markdown + JSON)
+
+## Domain Reference
+
+### MVP Domains (Fully Implemented)
+
+- **layer**: Layer violations, directory organization, dependency direction
+- **dep**: Circular dependencies, coupling, dependency direction violations
+- **api**: Public API design, exports management, breaking changes
+- **pure**: Side-effect isolation, testability, pure function violations
+- **complex**: Cognitive complexity, nesting, god functions
+
+### Additional Domains (Pluggable Stubs)
+
+- **error**: Error handling, error boundaries, error propagation
+- **obs**: Logging, observability, console usage
+- **type**: Type safety, type definitions, type exports
+- **async**: Async patterns, promise handling, race conditions
+- **ui**: React patterns, component design, rendering optimization
+- **perf**: Performance anti-patterns, resource leaks, blocking operations
+- **sec**: Security risks, XSS, injection, validation
+- **doc**: Documentation quality, API docs, comments
+- **test**: Test coverage, test quality, test maintainability
+
+## Output Formats
+
+### Evidence Schema (JSON)
+
+Every finding follows this schema:
+
+```json
+{
+  "id": "RG-LAYER-001",
+  "severity": "BLOCKER",
+  "area": "LAYER",
+  "checklist_ref": "C-LAYER-01",
+  "title": "Domain layer imports from presentation",
+  "status": "OPEN",
+  "confidence": "HIGH",
+  "evidence": {
+    "files": [{"path": "src/domain/user.ts", "diff_hunks": ["..."]}],
+    "dependency_trace": {"chain": ["..."], "direction_violation": true}
+  },
+  "impact": ["ARCH", "MAINTAINABILITY"],
+  "blast_radius": "MODULE",
+  "risk_if_merge": "Violates dependency inversion...",
+  "proposed_fix": ["1. Extract shared types...", "2. Use dependency injection..."],
+  "acceptance_criteria": "Domain layer has no imports from presentation",
+  "automatable": "PARTIAL",
+  "hard_gate_candidate": {
+    "rule_idea": "Detect imports from domain/* to presentation/*",
+    "implementation_hint": "AST analysis + import path checking"
+  }
+}
+```
+
+### Report Structure
+
+- **Summary**: Overview, changeset stats, signal summary
+- **Blockers**: Critical findings that should prevent merge
+- **Recommendations**: Important but non-blocking improvements
+- **HardGateCandidates**: Automatable rules to add to hard-gate
+- **Fix Commits**: Map of findings → commit hashes (if fixes applied)
+
+## Layered Override System
+
+Hierarchical precedence (highest to lowest):
+
+1. `review-system/paths/*.md` - Path-specific overrides
+2. `review-system/packages/<pkg>.md` - Package-specific overrides
+3. `review-system/stacks/<stack>.md` - Stack-specific overrides
+4. `review-system/MASTER.md` - Base configuration
+
+Override files can modify:
+- Check severity levels
+- Allowlist exceptions
+- Custom notes/rationale
+- Domain weights
+
+## Consistency with skill-creator
+
+This skill follows the same conventions as skill-creator:
+
+- **Directory layout**: `.shared/<skill>/` with `scripts/`, `data/`, standard structure
+- **CLI pattern**: Similar to `scripts/search.py` with consistent flags and output formatting
+- **Data organization**: CSV/JSON indexes in `data/`, hierarchical domain structure
+- **Output formats**: ASCII/Markdown/JSON with consistent formatting
+- **Reasoning rules**: CSV-based routing similar to `skill-reasoning.csv`
+
+## Examples
+
+### Example Command
+
+```bash
+python3 .shared/review-gate/scripts/review.py \
+  --base-branch main \
+  --stack nextjs \
+  --format markdown \
+  --ensure-tests-pass
+```
+
+### Example Output (Markdown)
+
+```markdown
+# Review Gate Report
+
+**Branch**: review-gate/20260127-refactor-abc123
+**Base**: main
+**Stack**: nextjs
+**Changeset**: 15 files, 234 additions, 89 deletions
+
+## Summary
+
+- 3 Blockers
+- 7 Recommendations
+- 2 HardGate Candidates
+
+## Blockers
+
+### [RG-LAYER-001] Domain layer imports from presentation
+**Severity**: BLOCKER | **Confidence**: HIGH | **Area**: LAYER
+
+**Evidence**:
+- File: `src/domain/user/service.ts:12`
+- Imports: `import { UserCard } from '@/presentation/components/UserCard'`
+
+**Impact**: ARCH, MAINTAINABILITY
+**Blast Radius**: MODULE
+
+**Proposed Fix**:
+1. Extract shared types to `src/types/user.ts`
+2. Remove presentation dependency from domain
+3. Use dependency injection for UI concerns
+
+**Acceptance Criteria**: Domain layer has zero imports from presentation layer
+
+---
+
+## Recommendations
+
+[... additional findings ...]
+
+## HardGate Candidates
+
+1. **Detect domain→presentation imports** (C-LAYER-01)
+   - Implementation: AST + import path analysis
+   - False positive risk: LOW
+   - Scope: TypeScript/JavaScript imports
+```
+
+## Notes
+
+- **NOT a linter**: Focus is architecture, not style
+- **Evidence-required**: All findings must have concrete proof
+- **Minimal changes**: Code modifications are scoped and traceable
+- **No new tests**: Only fixes to make existing tests pass
+- **Deterministic**: Same input always produces same output

package/.shared/review-gate/data/domains/api/anti_patterns.md

@@ -0,0 +1,39 @@
+# API Design Anti-Patterns
+
+## Anti-Pattern: Index File Cascade
+
+**Description**: Deeply nested index.ts files re-exporting everything
+
+**Detection Signals**:
+- index.ts files at 3+ levels
+- Circular dependency warnings
+- Import paths going through multiple index files
+
+**Why It's Bad**:
+- Creates tight coupling
+- Causes circular dependencies
+- Hard to track actual dependencies
+
+**Fix**:
+- Use package.json exports field
+- Export from root index.ts only
+- Remove intermediate index files
+
+## Anti-Pattern: Kitchen Sink Module
+
+**Description**: Single module exports everything
+
+**Detection Signals**:
+- Module with >20 exports
+- Unrelated functionality in same file
+- Module name is generic (utils, helpers, common)
+
+**Why It's Bad**:
+- Unclear module purpose
+- Forces importing unused code
+- Hard to maintain
+
+**Fix**:
+- Split into focused modules
+- Group related functionality
+- Use clear, specific names

package/.shared/review-gate/data/domains/api/checks.csv

@@ -0,0 +1,6 @@
+id,title,severity,description,evidence_requirements,automatable
+C-API-01,Deep index.ts files,RECOMMENDATION,Index files deeper than 2 levels risk circular deps,File paths,YES
+C-API-02,Default export overuse,RECOMMENDATION,Default exports used outside framework requirements,Export analysis,PARTIAL
+C-API-03,Breaking API change,BLOCKER,Public API modified without deprecation,API surface diff,PARTIAL
+C-API-04,Undocumented public API,RECOMMENDATION,Public export lacks JSDoc/TSDoc,Export + comment analysis,YES
+C-API-05,Inconsistent export pattern,RECOMMENDATION,Mix of named and default exports in same module,Export analysis,PARTIAL

package/.shared/review-gate/data/domains/api/hardgate_candidates.csv

@@ -0,0 +1,4 @@
+rule_id,rule_idea,implementation_hint,false_positive_risk,scope,example_pattern
+HG-API-01,Detect deep index.ts files,Count path depth of index.ts files,LOW,index.ts files,src/a/b/c/index.ts (depth > 2)
+HG-API-02,Require JSDoc for public exports,Check exported symbols for JSDoc comments,MEDIUM,Public API files,export function foo() without /** */
+HG-API-03,Detect default export outside pages/,Check for default exports in non-framework files,LOW,Non-page TypeScript files,export default in non-page files

package/.shared/review-gate/data/domains/api/recipes.md

@@ -0,0 +1,30 @@
+# API Design Recipes
+
+## Recipe: Remove Deep Index Files
+
+**Problem**: Multiple nested index.ts files causing coupling
+
+**Steps**:
+1. Identify all index.ts files >2 levels deep
+2. Move exports to root index.ts or package.json exports
+3. Remove intermediate index.ts files
+4. Update imports to use direct paths or root exports
+
+## Recipe: Convert Default to Named Exports
+
+**Problem**: Overuse of default exports
+
+**Steps**:
+1. Change `export default` to `export const/function`
+2. Update all import statements
+3. Verify no framework requirements for default export
+
+## Recipe: Document Public API
+
+**Problem**: Public exports lack documentation
+
+**Steps**:
+1. Add JSDoc/TSDoc comments to all public exports
+2. Include @param, @returns, @throws
+3. Add usage examples for complex APIs
+4. Document breaking changes and deprecations

package/.shared/review-gate/data/domains/async/anti_patterns.md

@@ -0,0 +1,7 @@
+# Async Anti-Patterns
+
+## Anti-Pattern: Fire and Forget
+
+**Description**: Promises without error handling
+
+**Fix**: Always handle rejections

package/.shared/review-gate/data/domains/async/checks.csv

@@ -0,0 +1,4 @@
+id,title,severity,description,evidence_requirements,automatable
+C-ASYNC-01,Unhandled promise rejection,RECOMMENDATION,Promise without catch or await,Code analysis,YES
+C-ASYNC-02,Race condition risk,RECOMMENDATION,Concurrent state mutations,Code flow analysis,NO
+C-ASYNC-03,Missing async/await,RECOMMENDATION,Promise chains instead of async/await,Code pattern,PARTIAL

package/.shared/review-gate/data/domains/async/hardgate_candidates.csv

@@ -0,0 +1,2 @@
+rule_id,rule_idea,implementation_hint,false_positive_risk,scope,example_pattern
+HG-ASYNC-01,Detect unhandled promises,AST analysis for promises without catch/await,MEDIUM,All async code,promise without .catch() or try-catch

package/.shared/review-gate/data/domains/async/recipes.md

@@ -0,0 +1,8 @@
+# Async Patterns Recipes
+
+## Recipe: Handle Promise Rejections
+
+**Steps**:
+1. Add try-catch to async functions
+2. Add .catch() to promise chains
+3. Handle errors appropriately

package/.shared/review-gate/data/domains/complex/anti_patterns.md

@@ -0,0 +1,39 @@
+# Complexity Anti-Patterns
+
+## Anti-Pattern: Arrow Code
+
+**Description**: Deeply nested if statements forming arrow shape
+
+**Detection Signals**:
+- Indentation >4 levels
+- Multiple nested if/for/while
+- Hard to follow control flow
+
+**Why It's Bad**:
+- Hard to read and understand
+- Difficult to test all paths
+- Error-prone to modify
+
+**Fix**:
+- Use early returns
+- Extract nested logic to functions
+- Flatten structure
+
+## Anti-Pattern: God Function
+
+**Description**: Single function doing everything
+
+**Detection Signals**:
+- Function >100 lines
+- Multiple responsibilities
+- High cyclomatic complexity
+
+**Why It's Bad**:
+- Hard to understand
+- Difficult to test
+- Violates single responsibility
+
+**Fix**:
+- Extract smaller functions
+- Each function does one thing
+- Use descriptive names

package/.shared/review-gate/data/domains/complex/checks.csv

@@ -0,0 +1,6 @@
+id,title,severity,description,evidence_requirements,automatable
+C-COMPLEX-01,Excessive nesting depth,RECOMMENDATION,Code has >4 levels of nesting,Indentation analysis,YES
+C-COMPLEX-02,Long function,RECOMMENDATION,Function exceeds 60 lines,Line count,YES
+C-COMPLEX-03,God function,RECOMMENDATION,Function has too many responsibilities,Complexity metrics,PARTIAL
+C-COMPLEX-04,High cyclomatic complexity,RECOMMENDATION,Function has >15 decision points,Complexity analysis,YES
+C-COMPLEX-05,Poor variable naming,RECOMMENDATION,Variables named a/b/x/temp without context,Identifier analysis,PARTIAL

package/.shared/review-gate/data/domains/complex/hardgate_candidates.csv

@@ -0,0 +1,5 @@
+rule_id,rule_idea,implementation_hint,false_positive_risk,scope,example_pattern
+HG-COMPLEX-01,Limit function length to 60 lines,Count lines between function declaration and closing brace,LOW,All functions,Functions with >60 lines
+HG-COMPLEX-02,Limit cyclomatic complexity to 15,Calculate decision points in function,LOW,All functions,Functions with >15 if/for/while/case
+HG-COMPLEX-03,Limit nesting depth to 4,Track indentation levels,LOW,All code,Code with >4 levels of nesting
+HG-COMPLEX-04,Flag single-letter variables,Check variable names against pattern,HIGH,All variables,Variables named a/b/c/x/y/z without context

package/.shared/review-gate/data/domains/complex/recipes.md

@@ -0,0 +1,68 @@
+# Complexity Reduction Recipes
+
+## Recipe: Reduce Nesting with Early Returns
+
+**Problem**: Deep nesting makes code hard to read
+
+**Steps**:
+1. Identify nested if statements
+2. Invert conditions and return early
+3. Flatten the code structure
+
+**Example**:
+```typescript
+// Before
+function process(data: Data) {
+  if (data) {
+    if (data.isValid) {
+      if (data.hasPermission) {
+        return doWork(data)
+      }
+    }
+  }
+  return null
+}
+
+// After
+function process(data: Data) {
+  if (!data) return null
+  if (!data.isValid) return null
+  if (!data.hasPermission) return null
+  return doWork(data)
+}
+```
+
+## Recipe: Extract Method
+
+**Problem**: Long function doing too much
+
+**Steps**:
+1. Identify logical sections
+2. Extract each section to named function
+3. Keep functions focused and small
+
+## Recipe: Replace Complex Condition with Function
+
+**Problem**: Complex boolean expressions
+
+**Steps**:
+1. Extract condition to named function
+2. Use descriptive name explaining intent
+3. Improve readability
+
+**Example**:
+```typescript
+// Before
+if (user.age >= 18 && user.hasLicense && !user.isSuspended) {
+  allowDriving()
+}
+
+// After
+function canDrive(user: User) {
+  return user.age >= 18 && user.hasLicense && !user.isSuspended
+}
+
+if (canDrive(user)) {
+  allowDriving()
+}
+```

package/.shared/review-gate/data/domains/dep/anti_patterns.md

@@ -0,0 +1,58 @@
+# Dependency Anti-Patterns
+
+## Anti-Pattern: Dependency Hell
+
+**Description**: Complex web of circular and tangled dependencies
+
+**Detection Signals**:
+- Multiple circular dependency warnings
+- Changes in one module break many others
+- Dependency graph looks like spaghetti
+
+**Why It's Bad**:
+- Hard to understand code flow
+- Difficult to test in isolation
+- Refactoring becomes risky
+
+**Fix**:
+- Map dependency graph
+- Break cycles systematically
+- Establish clear dependency direction
+
+## Anti-Pattern: God Object Dependency
+
+**Description**: One module that everything depends on
+
+**Detection Signals**:
+- Single module imported by >80% of codebase
+- Module has too many responsibilities
+- Changes to module require extensive testing
+
+**Why It's Bad**:
+- Single point of failure
+- Bottleneck for development
+- Hard to maintain and evolve
+
+**Fix**:
+- Split into focused modules
+- Use dependency inversion
+- Create clear interfaces
+
+## Anti-Pattern: Shotgun Surgery
+
+**Description**: Single change requires modifications in many modules
+
+**Detection Signals**:
+- Feature changes touch >10 files
+- Related logic scattered across codebase
+- High coupling between modules
+
+**Why It's Bad**:
+- Increases risk of bugs
+- Slows down development
+- Hard to ensure consistency
+
+**Fix**:
+- Colocate related functionality
+- Reduce coupling
+- Use events/observers for cross-cutting concerns

package/.shared/review-gate/data/domains/dep/checks.csv

@@ -0,0 +1,6 @@
+id,title,severity,description,evidence_requirements,automatable
+C-DEP-01,Circular dependency detected,BLOCKER,Circular import chain between modules,Dependency graph with cycle,YES
+C-DEP-02,High coupling between modules,RECOMMENDATION,Module imports too many other modules,Import count analysis,PARTIAL
+C-DEP-03,Upward dependency violation,BLOCKER,Lower layer depends on higher layer,Dependency trace + layer info,PARTIAL
+C-DEP-04,Tight coupling to external library,RECOMMENDATION,Direct usage of external library throughout codebase,Import analysis,NO
+C-DEP-05,Missing dependency abstraction,RECOMMENDATION,Concrete dependency instead of interface,Type analysis,NO

package/.shared/review-gate/data/domains/dep/hardgate_candidates.csv

@@ -0,0 +1,5 @@
+rule_id,rule_idea,implementation_hint,false_positive_risk,scope,example_pattern
+HG-DEP-01,Detect circular imports,Build import graph with DFS cycle detection,LOW,All TypeScript/JavaScript files,Import cycles in dependency graph
+HG-DEP-02,Limit module fan-out,Count imports per file and flag >15,MEDIUM,All source files,File with >15 import statements
+HG-DEP-03,Detect upward layer dependencies,Combine import analysis with layer classification,LOW,TypeScript files,Lower layer importing from higher layer
+HG-DEP-04,Flag direct external library usage in domain,Check domain/* files for external package imports,MEDIUM,domain/* files,"import axios/fetch/prisma in domain/*"

package/.shared/review-gate/data/domains/dep/recipes.md

@@ -0,0 +1,89 @@
+# Dependency Violation Recipes
+
+## Recipe: Break Circular Dependency
+
+**Problem**: Module A imports B, B imports A
+
+**Steps**:
+1. Identify the shared concern causing the cycle
+2. Extract shared types/interfaces to separate module
+3. Both A and B import from the new module
+4. Verify cycle is broken
+
+**Example**:
+```typescript
+// Before: Cycle between user.ts and order.ts
+// user.ts
+import { Order } from './order'
+export interface User { orders: Order[] }
+
+// order.ts
+import { User } from './user'
+export interface Order { user: User }
+
+// After: Extract to types
+// types.ts
+export interface UserRef { id: string; name: string }
+export interface OrderRef { id: string; total: number }
+
+// user.ts
+import { OrderRef } from './types'
+export interface User { orders: OrderRef[] }
+
+// order.ts
+import { UserRef } from './types'
+export interface Order { user: UserRef }
+```
+
+## Recipe: Reduce Module Coupling
+
+**Problem**: Module imports from too many other modules
+
+**Steps**:
+1. Identify common dependencies
+2. Group related functionality
+3. Create facade or aggregate module
+4. Reduce direct dependencies
+
+## Recipe: Abstract External Dependency
+
+**Problem**: External library used directly throughout code
+
+**Steps**:
+1. Create adapter interface in domain
+2. Implement adapter in infrastructure
+3. Inject adapter through dependency injection
+4. Replace direct library usage with adapter
+
+**Example**:
+```typescript
+// Before: Direct axios usage in domain
+// domain/user/service.ts
+import axios from 'axios'
+export async function getUser(id: string) {
+  return axios.get(`/api/users/${id}`)
+}
+
+// After: Abstract with adapter
+// domain/user/repository.ts
+export interface UserRepository {
+  getUser(id: string): Promise<User>
+}
+
+// infra/api/userApiRepository.ts
+import axios from 'axios'
+export class UserApiRepository implements UserRepository {
+  async getUser(id: string) {
+    const response = await axios.get(`/api/users/${id}`)
+    return mapToUser(response.data)
+  }
+}
+
+// domain/user/service.ts
+export class UserService {
+  constructor(private repo: UserRepository) {}
+  async getUser(id: string) {
+    return this.repo.getUser(id)
+  }
+}
+```

package/.shared/review-gate/data/domains/doc/anti_patterns.md

@@ -0,0 +1,7 @@
+# Documentation Anti-Patterns
+
+## Anti-Pattern: Obvious Comments
+
+**Description**: Comments that repeat code
+
+**Fix**: Remove or explain why, not what

package/.shared/review-gate/data/domains/doc/checks.csv

@@ -0,0 +1,4 @@
+id,title,severity,description,evidence_requirements,automatable
+C-DOC-01,Missing JSDoc for public API,RECOMMENDATION,Public function lacks documentation,Export + comment analysis,YES
+C-DOC-02,Outdated comments,RECOMMENDATION,Comments contradict code,Code analysis,NO
+C-DOC-03,Complex logic without explanation,RECOMMENDATION,Complex code lacks why comment,Complexity + comment analysis,NO

package/.shared/review-gate/data/domains/doc/hardgate_candidates.csv

@@ -0,0 +1,2 @@
+rule_id,rule_idea,implementation_hint,false_positive_risk,scope,example_pattern
+HG-DOC-01,Require JSDoc for public exports,Check exported functions for /** */ comments,MEDIUM,Public API files,export function without JSDoc

package/.shared/review-gate/data/domains/doc/recipes.md

@@ -0,0 +1,8 @@
+# Documentation Recipes
+
+## Recipe: Add JSDoc to Public API
+
+**Steps**:
+1. Add /** */ comment above export
+2. Document @param and @returns
+3. Include usage example

package/.shared/review-gate/data/domains/error/anti_patterns.md

@@ -0,0 +1,7 @@
+# Error Handling Anti-Patterns
+
+## Anti-Pattern: Swallowing Errors
+
+**Description**: Catch blocks that ignore errors
+
+**Fix**: Log and handle appropriately

package/.shared/review-gate/data/domains/error/checks.csv

@@ -0,0 +1,4 @@
+id,title,severity,description,evidence_requirements,automatable
+C-ERROR-01,Empty catch block,RECOMMENDATION,Error caught but not handled,Code pattern,YES
+C-ERROR-02,Generic error thrown,RECOMMENDATION,Throwing generic Error instead of custom type,Error analysis,PARTIAL
+C-ERROR-03,Missing error boundary,RECOMMENDATION,No error handling for critical path,Code flow analysis,NO