ace-review 0.49.0

data/handbook/workflow-instructions/review/run.wf.md

@@ -0,0 +1,262 @@
+---
+doc-type: workflow
+title: Code Review Workflow
+purpose: Review code with preset and plan feedback application
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# Code Review Workflow
+
+## Goal
+
+Review code using ace-review, verify feedback items, and create a plan for applying fixes.
+
+## Arguments
+
+- `$1`: Preset name (optional). Run `ace-review --list-presets` to see options.
+- `$2+`: Subject(s) using `type:value` syntax (optional, additive to preset):
+
+  **IMPORTANT: The type prefix is REQUIRED for all subjects except keywords**
+
+  - `staged`, `working` - keywords (no prefix needed)
+  - `diff:origin/main..HEAD` - git range (prefix required)
+  - `pr:123` - PR diff (prefix required)
+  - `files:lib/**/*.rb` - file pattern (prefix required)
+  - `task:145` - task context (prefix required)
+
+## Instructions
+
+### Step 1: Run Code Review
+
+```bash
+# Default preset
+ace-review --auto-execute
+
+# With preset
+ace-review --preset $1 --auto-execute
+
+# With subject(s) - additive to preset
+ace-review --subject "$2" --auto-execute
+
+# File pattern review (NOTE: files: prefix is REQUIRED)
+ace-review --preset spec --subject "files:.ace-taskflow/**/*.md" --auto-execute
+
+# Multiple subjects merge automatically
+ace-review --subject pr:76 --subject files:CHANGELOG.md --auto-execute
+```
+
+**Important for Claude Code**: Run with 15-minute timeout (900000ms) and wait for completion inline (not background). Review typically takes 3-5 minutes.
+
+#### Execution Guard (Mandatory)
+
+- Completion is defined by **process exit** (success or failure), not by partial output.
+- Do **not** treat temporary silence/no new output as completion.
+- Do **not** run any Step 2+ commands until Step 1 process exit is confirmed.
+- If 15-minute timeout (900000ms) is reached, report timeout and last observed output, then stop dependent steps.
+
+Wait for the review process to exit. Note the session directory path from the output.
+
+The review generates:
+- LLM model reviews (e.g., `review-gemini.md`)
+- Feedback items in `feedback/` directory
+
+### Step 2: List Feedback Items
+
+List the feedback items extracted from the review:
+
+```bash
+ace-review-feedback list --status draft
+```
+
+**Precondition**: Run this step only after Step 1 process exit is confirmed.
+
+When session ambiguity is possible, use explicit session path from Step 1:
+
+```bash
+ace-review-feedback list --status draft --session <session-dir-from-step-1>
+```
+
+This shows all draft feedback items with their IDs, severity, and summaries.
+
+#### Understanding Feedback Context
+
+Feedback items are **session-scoped**. The `feedback list` command discovers items based on:
+1. Explicit `--session <path>` flag (if provided)
+2. `.ace-review-session` cache file in current directory (auto-created after reviews)
+
+If `feedback list` returns empty after a review, first verify Step 1 process completion.
+The session may not be linked to current context.
+Use `ace-review-feedback list --session <session-dir>` to list from a specific session:
+
+```bash
+# List feedback from a specific session (path shown in review output)
+ace-review-feedback list --session .ace-local/review/sessions/review-8p2pk3
+```
+
+### Step 3: Verify Feedback Items
+
+**For thorough verification**, use the dedicated verification workflow:
+
+```
+ace-bundle wfi://review/verify-feedback
+```
+
+This workflow guides you through multi-dimensional claim analysis:
+- **Existence claims**: Does the code/issue actually exist?
+- **Scope claims**: Does the issue apply where claimed (CI, production, etc.)?
+- **Documentation claims**: Are there docs/handling elsewhere?
+- **Pattern claims**: Is this consistent with codebase patterns?
+
+**For quick verification** of straightforward items:
+
+```bash
+# Read the finding details
+ace-review-feedback show {id}
+
+# Verify and mark result
+ace-review-feedback verify {id} --valid --research "Confirmed: issue exists at line X"
+ace-review-feedback verify {id} --invalid --research "False positive: handled by Y"
+```
+
+**Categorization guide:**
+
+| Result | Command | When |
+|--------|---------|------|
+| ✅ VALID | `--valid` | Issue confirmed in code |
+| ❌ INVALID | `--invalid` | **False positive** - claim is factually incorrect |
+| ✅ DONE | `feedback resolve {id}` | Already fixed in this PR |
+| ⏭️ SKIP | `verify --skip --research "Design: ..."` | **Correct finding**, but not being fixed |
+| 📋 DEFER | `verify --skip --research "Tracked in task XXX"` | Important, but not this PR (create task first) |
+
+**Key distinction:**
+- `verify --invalid`: The finding is **wrong** (false positive)
+  - "Code doesn't exist" → Actually exists
+  - "Missing validation" → Exists elsewhere
+  - "Fails in CI" → Doesn't run in CI
+- `verify --skip`: The finding is **correct**, but you're not fixing it
+  - Design decision: Intentional choice
+  - Deferred: Tracking in separate task
+
+**Skip verification for:**
+- Low priority items (verify only if time permits)
+- Documentation-only suggestions
+- Style/formatting recommendations
+
+### Step 4: List Pending Items
+
+After verification, list items ready to work on:
+
+```bash
+ace-review-feedback list --status pending
+```
+
+This shows only verified valid items that need fixing.
+
+### Step 5: Apply Priority Threshold
+
+**Default behavior**: Implement **Medium and higher** severity items (skip Low).
+
+This means:
+- 🔴 Critical → Implement
+- 🟡 High → Implement
+- 🟢 Medium → Implement
+- 🔵 Low → Skip (unless explicitly requested)
+
+### Step 6: Implement Fixes
+
+For each pending item:
+
+1. **Read the full details:**
+   ```bash
+   ace-review-feedback show {id}
+   ```
+
+2. **Implement the fix** based on the recommendation
+
+3. **Mark as resolved:**
+   ```bash
+   ace-review-feedback resolve {id} --resolution "Fixed in commit abc123"
+   ```
+
+4. **Commit the fix** with a clear message referencing the feedback item
+
+### Step 7: Handle Not-Applicable Items
+
+Before skipping, complete the verification checklist:
+
+1. **Read the code** - Does the issue actually still exist?
+2. **Check current changes** - Was this already fixed in this PR?
+3. **Consider effort** - Is this a quick win (< 5 min) that should just be done?
+
+For items that won't be fixed in this PR:
+
+```bash
+# Design decision - intentionally this way
+ace-review-feedback verify {id} --skip --research "Design: uses polling for simplicity"
+
+# Important but deferred - ALWAYS create/reference a task
+ace-review-feedback verify {id} --skip --research "Tracked in task 253"
+```
+
+**Never skip with "out of scope"** - either:
+- It's a design decision (explain why)
+- It needs a follow-up task (create one and reference it)
+
+## Quick Reference
+
+```bash
+# Discovery
+ace-review --list-presets   # Available presets
+ace-review --list-prompts   # Available prompt modules
+
+# Subject types (type:value syntax)
+--subject staged                    # Staged changes (keyword)
+--subject working                   # Unstaged changes (keyword)
+--subject diff:origin/main..HEAD    # Git range
+--subject pr:123                    # PR diff
+--subject files:lib/**/*.rb         # File pattern
+--subject task:145                  # Task context
+
+# Feedback commands
+ace-review-feedback list                      # All feedback
+ace-review-feedback list --status draft       # Unverified items
+ace-review-feedback list --status pending     # Verified valid items
+ace-review-feedback list --session <path>     # From specific session
+ace-review-feedback show {id}                 # Full item details
+ace-review-feedback verify {id} --valid       # Mark as valid
+ace-review-feedback verify {id} --invalid     # Mark as false positive
+ace-review-feedback verify {id} --skip        # Mark as skipped
+ace-review-feedback resolve {id}              # Mark as fixed
+
+# Common patterns
+ace-review --auto-execute                                  # Default preset
+ace-review --subject staged --auto-execute                 # Staged only
+ace-review --subject diff:origin/main..HEAD --auto-execute # vs main
+ace-review --subject pr:76 --subject files:README.md --auto-execute  # Combined
+
+# Debug
+ace-review --dry-run   # See what would run
+```
+
+## Common Mistakes
+
+❌ **Wrong**: `ace-review --subject path/to/file`
+✅ **Correct**: `ace-review --subject files:path/to/file`
+
+❌ **Wrong**: `ace-review --subject 123`
+✅ **Correct**: `ace-review --subject pr:123`
+
+❌ **Wrong**: `ace-review --subject origin/main..HEAD`
+✅ **Correct**: `ace-review --subject diff:origin/main..HEAD`
+
+The type prefix (`files:`, `pr:`, `diff:`, `task:`) is **required** for all subjects except the keywords `staged` and `working`.
+
+## Success Criteria
+
+- [ ] Review completed with feedback items
+- [ ] Feedback items verified (Critical/High priority)
+- [ ] False positives marked as invalid
+- [ ] Confirmed items implemented with commits
+- [ ] Items marked as resolved with commit references

data/handbook/workflow-instructions/review/verify-feedback.wf.md

@@ -0,0 +1,286 @@
+---
+doc-type: workflow
+title: Verify Feedback Workflow
+purpose: Verify feedback items through multi-dimensional claim analysis
+ace-docs:
+  last-updated: 2026-03-12
+  last-checked: 2026-03-21
+---
+
+# Verify Feedback Workflow
+
+## Goal
+
+Verify each feedback item through systematic claim analysis, marking items as valid, invalid, or skipped based on evidence gathered from the codebase, documentation, and execution context.
+
+## Why This Workflow Exists
+
+Simple verification ("does this code exist?") catches some false positives, but misses **scope claims** - assertions about where or when code executes. For example:
+
+- "E2E tests may fail in CI" → E2E tests don't run in CI (scope error)
+- "Missing API key validation" → Keys are validated in middleware (location error)
+- "Thread-unsafe code" → Code only runs in single-threaded context (context error)
+
+This workflow ensures each claim dimension is verified.
+
+## Arguments
+
+- `--session <path>` - Specific session directory (optional)
+- `--status draft` - Filter to unverified items (default)
+
+## Prerequisites
+
+Before running this workflow, you need feedback items from a code review:
+1. Run a code review: `ace-bundle wfi://review/run` or `ace-bundle wfi://review/pr`
+2. Feedback items will be in `draft` status
+
+## Instructions
+
+### Step 1: List Draft Feedback Items
+
+```bash
+# List unverified items
+ace-review-feedback list --status draft
+
+# From specific session
+ace-review-feedback list --status draft --session <path>
+```
+
+If no items appear, the review may not have generated extractable feedback.
+
+### Step 2: For Each Item, Run Multi-Dimensional Verification
+
+For each feedback item, verify claims across multiple dimensions before marking valid/invalid/skipped.
+
+#### 2a. Read the Feedback Item
+
+```bash
+ace-review-feedback show <id>
+```
+
+Identify the claim being made. Common claim types:
+
+| Claim Type | Example | Verification Question |
+|------------|---------|----------------------|
+| **Existence** | "Method X is undefined" | Does X exist in codebase? |
+| **Scope** | "Fails in CI environment" | Does this code run in CI? |
+| **Documentation** | "Behavior is undocumented" | Are there docs elsewhere? |
+| **Pattern** | "Inconsistent with codebase" | What patterns exist? |
+| **Security** | "Exposes sensitive data" | What data flows here? |
+| **Performance** | "N+1 query issue" | How is this code called? |
+
+#### 2b. Verify Each Claim Dimension
+
+For each feedback item, work through applicable verification questions:
+
+**1. Is the factual claim true?**
+- If "X doesn't exist" → Search for X
+- If "missing validation" → Check the specific code path
+- If "undefined reference" → Verify the symbol resolution
+
+```bash
+# Example: Verify class exists
+grep -rn "class TaskPatternExtractor" ace-git/lib/
+
+# Example: Check for validation
+grep -rn "validate" path/to/file.rb
+```
+
+**2. Does the scope match?**
+- If "fails in CI" → Does this code execute in CI?
+- If "production issue" → Does config differ in production?
+- If "user-facing" → Is this actually exposed to users?
+
+```bash
+# Example: Check CI workflow for test execution
+cat .github/workflows/test.yml | grep -A5 "run:"
+
+# Example: Check if E2E tests run in CI
+grep -rn "e2e\|end-to-end" .github/workflows/
+```
+
+**3. Is it already addressed elsewhere?**
+- If "missing docs" → Check README, handbook, inline comments
+- If "no error handling" → Check if caller handles errors
+- If "missing validation" → Check middleware/filters
+
+```bash
+# Example: Check for documentation
+grep -rn "api-key\|API_KEY" README.md docs/ handbook/
+
+# Example: Check frontmatter for requirements
+head -30 path/to/file.md
+```
+
+**4. Does it follow established patterns?**
+- If "inconsistent approach" → What do similar files do?
+- If "should use X instead" → What's the project standard?
+
+```bash
+# Example: Check existing patterns
+grep -rn "def self\." lib/ace/review/atoms/ | head -20
+```
+
+#### 2c. Document Verification Result
+
+Based on verification:
+
+**Valid Finding** - All claim dimensions check out:
+```bash
+ace-review-feedback verify <id> --valid --research "Confirmed: <evidence>"
+```
+
+**Invalid Finding** - Any claim dimension fails:
+```bash
+ace-review-feedback verify <id> --invalid --research "<dimension> incorrect: <evidence>"
+```
+
+**Skip Finding** - Valid but not being fixed:
+```bash
+ace-review-feedback verify <id> --skip --research "Design: <reason>"
+ace-review-feedback verify <id> --skip --research "Tracked in task XXX"
+```
+
+### Step 3: Common False Positive Patterns
+
+Watch for these scope errors that simple verification misses:
+
+| False Positive Pattern | How to Detect |
+|----------------------|---------------|
+| "CI environment" claims | Check if code actually runs in CI workflows |
+| "Production" claims | Verify environment-specific behavior |
+| "External API" claims | Check if feature is actually enabled/used |
+| "Thread safety" claims | Verify concurrency context |
+| "User input" claims | Trace actual data flow |
+
+### Step 4: Verification Decision Table
+
+| Factual Claim | Scope Correct | Addressed | Verdict |
+|--------------|---------------|-----------|---------|
+| True | True | No | **VALID** |
+| True | True | Yes | **INVALID** (already addressed) |
+| True | False | - | **INVALID** (scope error) |
+| False | - | - | **INVALID** (factual error) |
+
+### Step 5: Final Summary
+
+After verifying all items:
+
+```bash
+# Check verification status
+ace-review-feedback list
+
+# Should show items as pending (valid) or invalid
+```
+
+## Examples
+
+### Example 1: CI Scope Error
+
+**Feedback**: "E2E tests may fail in CI environments without API keys"
+
+**Verification**:
+1. Factual: Do E2E tests make API calls? → Yes
+2. Scope: Do E2E tests run in CI? → **NO** (check workflows)
+3. Addressed: Are API requirements documented? → Yes (frontmatter)
+
+**Result**: INVALID - scope claim is wrong
+```bash
+ace-review-feedback verify <id> --invalid --research "E2E tests are agent-executed, not CI. API requirements documented in frontmatter."
+```
+
+### Example 2: Valid Finding
+
+**Feedback**: "Missing null check in user_handler.rb:45"
+
+**Verification**:
+1. Factual: Is there a null check? → No
+2. Scope: Can this receive null? → Yes (from API response)
+3. Addressed: Is null handled elsewhere? → No
+
+**Result**: VALID
+```bash
+ace-review-feedback verify <id> --valid --research "Confirmed: API can return null, no check present"
+```
+
+### Example 3: Location Error
+
+**Feedback**: "No input validation for user email"
+
+**Verification**:
+1. Factual: Is email validated in handler? → No
+2. Scope: Is this the entry point? → Yes
+3. Addressed: Is validation elsewhere? → **YES** (middleware)
+
+**Result**: INVALID - validation exists in different location
+```bash
+ace-review-feedback verify <id> --invalid --research "Email validated in AuthMiddleware:23"
+```
+
+## Quick Reference
+
+> **Tip**: Exact flag syntax per subcommand is available in the embedded `<feedback_cli_reference>` section above (loaded via ace-bundle).
+
+```bash
+# List items to verify
+ace-review-feedback list --status draft
+
+# Show item details
+ace-review-feedback show <id>
+
+# Mark as valid (confirmed issue)
+ace-review-feedback verify <id> --valid --research "Evidence..."
+
+# Mark as invalid (false positive)
+ace-review-feedback verify <id> --invalid --research "Reason..."
+
+# Mark as skipped (valid but not fixing)
+ace-review-feedback verify <id> --skip --research "Design: reason..."
+
+# Search helpers
+grep -rn "pattern" path/           # Find code
+cat file | head -30                # Check frontmatter
+ls .github/workflows/              # Check CI config
+```
+
+## Choosing Between Verification Modes
+
+All three modes archive feedback items, but they mean different things:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Is the feedback claim factually correct?                        │
+├─────────────────┬───────────────────────────────────────────────┤
+│  NO             │  YES                                          │
+│  → verify --invalid  │  → Are you fixing it?                      │
+│  (False positive)  │     ├─ YES → verify --valid (then resolve)  │
+│                    │     └─ NO → verify --skip "..."            │
+│                    │           (Not applicable)                  │
+└────────────────────┴─────────────────────────────────────────────┘
+```
+
+| Question | `verify --invalid` | `verify --skip` |
+|----------|-------------------|-----------------|
+| Is the claim factually wrong? | ✅ Yes | ❌ No |
+| Is the finding correct but not fixed? | ❌ No | ✅ Yes |
+
+### Quick Examples
+
+**`verify --invalid`** - The finding is incorrect:
+- "Code doesn't exist" → Actually exists
+- "Missing validation" → Exists elsewhere
+- "Fails in CI" → Doesn't run in CI
+
+**`verify --skip`** - The finding is correct but not being fixed:
+- "Design: using polling for simplicity"
+- "Tracked in task 253"
+- "Duplicate of abc120"
+
+## Success Criteria
+
+- [ ] Each draft feedback item reviewed
+- [ ] Factual claims verified against codebase
+- [ ] Scope claims verified (where/when code executes)
+- [ ] Existing documentation/handling checked
+- [ ] Each item marked valid or invalid with research notes
+- [ ] No items left in draft status