specsmd 0.0.0-dev.6 → 0.0.0-dev.61

package/flows/fire/agents/builder/skills/code-review/references/auto-fix-rules.md

@@ -0,0 +1,212 @@
+# Auto-Fix Rules
+
+This reference defines the criteria for determining whether an issue can be auto-fixed or requires user confirmation.
+
+---
+
+## Decision Framework
+
+```
+CAN AUTO-FIX if ALL of these are true:
+├── Change is mechanical (not semantic)
+├── Change follows existing pattern in codebase
+├── Change has no functional impact
+├── Change is universally agreed best practice
+├── Reverting is trivial if wrong
+└── Tests will still pass (verified after fix)
+
+MUST CONFIRM if ANY of these are true:
+├── Change affects behavior/functionality
+├── Change requires judgment call
+├── Change involves security implications
+├── Change affects public API
+├── Multiple valid approaches exist
+├── Change is significant (>10 lines affected)
+└── Change could break dependent code
+```
+
+---
+
+## Auto-Fix Criteria by Category
+
+### 1. Removal Operations (SAFE)
+
+These can be auto-fixed because removal of unused code has no functional impact:
+
+| Operation | Criteria | Safe Because |
+|-----------|----------|--------------|
+| Remove unused import | Import not referenced anywhere | No runtime effect |
+| Remove unused variable | Variable never read | No runtime effect |
+| Remove console.log | Debug statement | No production effect |
+| Remove console.debug | Debug statement | No production effect |
+| Remove debugger | Debug statement | No production effect |
+| Remove trailing whitespace | Whitespace only | No code effect |
+| Remove empty lines (excess) | >2 consecutive blank lines | Formatting only |
+
+### 2. Formatting Operations (SAFE)
+
+These can be auto-fixed because they don't change semantics:
+
+| Operation | Criteria | Safe Because |
+|-----------|----------|--------------|
+| Sort imports | Reorder import statements | No runtime effect |
+| Standardize quotes | Use project's quote style | String value unchanged |
+| Add missing semicolons | Project uses semicolons | Parser handles both |
+| Fix indentation | Match project indent style | Whitespace only |
+| Add trailing newline | File doesn't end with newline | POSIX standard |
+
+### 3. Simple Substitutions (SAFE with verification)
+
+These can be auto-fixed but require test verification:
+
+| Operation | Criteria | Verify |
+|-----------|----------|--------|
+| `var` → `const` | Variable never reassigned | Run tests |
+| `var` → `let` | Variable is reassigned | Run tests |
+| `==` → `===` | Comparing same types | Run tests |
+| `!=` → `!==` | Comparing same types | Run tests |
+
+---
+
+## Must-Confirm Criteria
+
+### 1. Behavioral Changes
+
+Any change that could affect runtime behavior:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Add null check | Changes control flow |
+| Add try/catch | Changes error handling |
+| Add validation | May reject valid input |
+| Change function signature | Affects callers |
+| Add/remove async | Changes execution model |
+| Modify return value | Affects callers |
+
+### 2. Security Changes
+
+All security-related changes require confirmation:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Add input validation | May have false positives |
+| Add authentication | May break intended access |
+| Add authorization | May be too restrictive |
+| Change crypto | May have compatibility issues |
+| Add rate limiting | May affect legitimate users |
+
+### 3. Architectural Changes
+
+Changes affecting code structure:
+
+| Change | Why Confirm |
+|--------|-------------|
+| Extract function | Multiple valid ways |
+| Move code to different file | Affects imports |
+| Add abstraction layer | Judgment on necessity |
+| Change dependency injection | Affects instantiation |
+| Modify error propagation | Affects error handling chain |
+
+### 4. Size Threshold
+
+Changes affecting many lines:
+
+| Threshold | Action |
+|-----------|--------|
+| 1-5 lines | Can auto-fix if mechanical |
+| 6-10 lines | Prefer confirmation |
+| >10 lines | Must confirm |
+
+---
+
+## Rollback Protocol
+
+If auto-fix causes test failure:
+
+```
+1. Immediately revert ALL auto-fix changes
+2. Move the fix to CONFIRM category
+3. Report: "Auto-fix for X caused test failure, moved to suggestions"
+4. Continue with remaining auto-fixes
+5. Re-run tests after each batch
+```
+
+---
+
+## Project-Specific Overrides
+
+The project can customize auto-fix behavior in `.specs-fire/standards/coding-standards.md`:
+
+```yaml
+# In coding-standards.md frontmatter
+auto_fix:
+  allow:
+    - unused_imports
+    - console_statements
+    - trailing_whitespace
+  deny:
+    - quote_style  # Team prefers manual control
+    - semicolons   # Mixed codebase
+
+  # Custom patterns to auto-remove
+  remove_patterns:
+    - "// TODO: remove"
+    - "// DEBUG"
+```
+
+If `auto_fix` section exists, respect project preferences.
+If not specified, use default rules from this document.
+
+---
+
+## Examples
+
+### Auto-Fix Example
+
+**Before:**
+```javascript
+import { unused } from './module';  // unused import
+import { used } from './other';
+
+function process() {
+  console.log('debug');  // debug statement
+  const result = used();
+  return result;
+}
+```
+
+**After (auto-fixed):**
+```javascript
+import { used } from './other';
+
+function process() {
+  const result = used();
+  return result;
+}
+```
+
+**Report:**
+- Removed unused import `unused` from `./module`
+- Removed console.log statement
+
+### Confirm Example
+
+**Issue Detected:**
+```javascript
+function getUser(id) {
+  return db.query(`SELECT * FROM users WHERE id = ${id}`);
+}
+```
+
+**Suggested Fix:**
+```javascript
+function getUser(id) {
+  return db.query('SELECT * FROM users WHERE id = ?', [id]);
+}
+```
+
+**Why Confirm:**
+- Security fix (SQL injection)
+- Changes how query is constructed
+- May have edge cases with ID format
+- Requires understanding of db.query API

package/flows/fire/agents/builder/skills/code-review/references/review-categories.md

@@ -0,0 +1,154 @@
+# Code Review Categories
+
+This reference defines what the code-review skill checks for in each category.
+
+---
+
+## 1. Code Quality
+
+Issues related to code cleanliness and maintainability.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Unused imports | Import not referenced in file | Remove import |
+| Unused variables | Variable declared but never used | Remove declaration |
+| Console statements | `console.log`, `console.debug`, `print()` | Remove statement |
+| Commented-out code | Large blocks of commented code | Remove comments |
+| Trailing whitespace | Whitespace at end of lines | Trim whitespace |
+| Missing semicolons | JS/TS without semicolons (if project uses them) | Add semicolons |
+| Inconsistent quotes | Mixed single/double quotes | Standardize |
+| Empty blocks | Empty if/else/try/catch with no comment | Add TODO comment |
+| Debugger statements | `debugger` keyword | Remove statement |
+
+### Requires Confirmation
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Long functions | Function > 50 lines | Requires judgment on how to split |
+| Deep nesting | > 4 levels of nesting | Multiple valid refactoring approaches |
+| Duplicate code | Similar code blocks (>10 lines) | May be intentional |
+| Magic numbers | Hardcoded numbers without context | Need to understand meaning |
+| Complex conditionals | Complex boolean expressions | May need domain knowledge |
+
+---
+
+## 2. Security
+
+Issues that could lead to security vulnerabilities.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Hardcoded localhost | `localhost` or `127.0.0.1` in production code | Flag but usually intentional |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Risk |
+|-------|-----------|------|
+| Hardcoded secrets | API keys, passwords, tokens in code | Critical - secrets exposure |
+| SQL injection | String concatenation in SQL queries | Critical - data breach |
+| XSS vulnerabilities | Unescaped user input in HTML | High - script injection |
+| Command injection | User input in shell commands | Critical - RCE |
+| Path traversal | User input in file paths | High - unauthorized access |
+| Missing input validation | User input used without validation | Medium - various attacks |
+| Insecure crypto | Weak algorithms (MD5, SHA1 for passwords) | High - broken encryption |
+| CORS misconfiguration | `Access-Control-Allow-Origin: *` | Medium - CSRF |
+| Missing auth checks | Endpoints without authentication | High - unauthorized access |
+| Sensitive data in logs | PII, passwords logged | Medium - data leak |
+
+---
+
+## 3. Architecture
+
+Issues related to code organization and design.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Import order | Imports not grouped/sorted | Sort imports |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Wrong layer | Business logic in controller, DB in UI | Requires understanding architecture |
+| Missing error handling | No try/catch for async/IO operations | May be intentional propagation |
+| Tight coupling | Direct dependencies on concrete classes | Multiple valid solutions |
+| Missing abstraction | Repeated patterns that could be extracted | Judgment on when to abstract |
+| Circular dependencies | Module A imports B, B imports A | Requires refactoring design |
+| God class/function | Class/function doing too many things | Domain knowledge needed |
+| Inconsistent patterns | Different approaches for same problem | Need to pick canonical approach |
+| Missing logging | No logging for important operations | Need to understand what matters |
+| Synchronous blocking | Blocking calls in async context | May need architecture change |
+
+---
+
+## 4. Testing
+
+Issues related to test quality and coverage.
+
+### Auto-Fixable
+
+| Issue | Detection | Fix |
+|-------|-----------|-----|
+| Console in tests | `console.log` in test files | Remove statement |
+
+### Requires Confirmation (ALWAYS)
+
+| Issue | Detection | Why Confirm |
+|-------|-----------|-------------|
+| Missing tests | New function without corresponding test | Need to understand what to test |
+| Missing edge cases | Tests only cover happy path | Need domain knowledge |
+| Brittle tests | Tests rely on implementation details | Multiple valid approaches |
+| Missing assertions | Test runs but doesn't assert | May be setup test |
+| Test coverage gaps | Lines not covered by tests | Need to prioritize |
+| Flaky test patterns | Random data, timing dependencies | Need to understand intent |
+| Missing error tests | No tests for error conditions | Need to identify error cases |
+| Mock overuse | Everything mocked, no integration | Judgment on test strategy |
+
+---
+
+## Language-Specific Checks
+
+### JavaScript/TypeScript
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| `var` instead of `let/const` | Quality | Yes |
+| `==` instead of `===` | Quality | Yes (with caution) |
+| Missing `await` | Quality | Confirm |
+| `any` type usage | Quality | Confirm |
+| Missing null checks | Security | Confirm |
+
+### Go
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| Ignored error returns | Quality | Confirm |
+| Naked returns | Quality | Confirm |
+| Empty interface{} | Quality | Confirm |
+| Missing context | Architecture | Confirm |
+
+### Python
+
+| Issue | Category | Auto-Fix |
+|-------|----------|----------|
+| Bare except | Quality | Confirm |
+| Mutable default args | Quality | Confirm |
+| Missing type hints | Quality | Confirm |
+| `import *` | Quality | Yes |
+
+---
+
+## Severity Levels
+
+| Level | Description | Action |
+|-------|-------------|--------|
+| **Critical** | Security vulnerability, data loss risk | MUST address |
+| **High** | Significant quality/maintainability issue | SHOULD address |
+| **Medium** | Best practice violation | CONSIDER addressing |
+| **Low** | Minor style/preference issue | OPTIONAL |

package/flows/fire/agents/builder/skills/code-review/templates/review-report.md.hbs

@@ -0,0 +1,120 @@
+# Code Review Report
+
+**Run**: {{run_id}}
+**Intent**: {{intent_id}}
+**Reviewed**: {{timestamp}}
+**Files Reviewed**: {{files_count}}
+
+---
+
+## Summary
+
+| Category | Auto-Fixed | Applied | Skipped |
+|----------|------------|---------|---------|
+| Code Quality | {{quality.auto_fixed}} | {{quality.applied}} | {{quality.skipped}} |
+| Security | {{security.auto_fixed}} | {{security.applied}} | {{security.skipped}} |
+| Architecture | {{architecture.auto_fixed}} | {{architecture.applied}} | {{architecture.skipped}} |
+| Testing | {{testing.auto_fixed}} | {{testing.applied}} | {{testing.skipped}} |
+| **Total** | **{{totals.auto_fixed}}** | **{{totals.applied}}** | **{{totals.skipped}}** |
+
+**Tests Status**: {{#if tests_passing}}Passing{{else}}Failed{{/if}}
+
+---
+
+## Files Reviewed
+
+{{#each files_reviewed}}
+- `{{path}}` ({{type}})
+{{/each}}
+
+---
+
+## Auto-Fixed Issues
+
+{{#if auto_fixed}}
+These issues were automatically fixed (mechanical, non-semantic changes):
+
+{{#each auto_fixed}}
+### {{add @index 1}}. [{{category}}] {{title}}
+
+- **File**: `{{file}}:{{line}}`
+- **Description**: {{description}}
+- **Diff**:
+
+```diff
+{{diff}}
+```
+
+{{/each}}
+{{else}}
+No auto-fixes applied.
+{{/if}}
+
+---
+
+## Applied Suggestions
+
+{{#if applied}}
+These suggestions were approved and applied:
+
+{{#each applied}}
+### {{add @index 1}}. [{{category}}] {{title}}
+
+- **File**: `{{file}}:{{line}}`
+- **Description**: {{description}}
+- **Rationale**: {{rationale}}
+- **Risk Level**: {{risk}}
+- **Approved**: {{approved_at}}
+- **Diff**:
+
+```diff
+{{diff}}
+```
+
+{{/each}}
+{{else}}
+No suggestions were applied.
+{{/if}}
+
+---
+
+## Skipped Suggestions
+
+{{#if skipped}}
+These suggestions were identified but not applied:
+
+{{#each skipped}}
+### {{add @index 1}}. [{{category}}] {{title}}
+
+- **File**: `{{file}}:{{line}}`
+- **Description**: {{description}}
+- **Rationale**: {{rationale}}
+- **Risk Level**: {{risk}}
+- **Reason Skipped**: {{skip_reason}}
+
+{{/each}}
+{{else}}
+No suggestions were skipped.
+{{/if}}
+
+---
+
+## Project Tooling Used
+
+{{#if linters_used}}
+The following project linters were detected and used:
+
+{{#each linters_used}}
+- **{{name}}**: {{config_file}}
+{{/each}}
+{{else}}
+No project linters detected. Used built-in review rules.
+{{/if}}
+
+---
+
+## Standards Referenced
+
+{{#each standards_loaded}}
+- `{{path}}`
+{{/each}}