@ktpartners/dgs-platform 2.6.2

package/deliver-great-systems/workflows/codereview.md

@@ -0,0 +1,526 @@
+<purpose>
+Multi-agent code review that runs 3 passes of 3 parallel agents each (9 total reviews) against the diff produced by a plan execution. Auto-fixes low-risk issues in a separate commit. Logs ambiguous CRITICAL/HIGH findings as deviations rather than prompting the user (non-interactive mode).
+</purpose>
+
+<context_tier>none</context_tier>
+
+<inputs>
+- PHASE: phase identifier
+- PLAN: plan number
+- PLAN_PATH: path to the PLAN.md file
+- PHASE_DIR: phase directory path
+- DIFF_REF: git ref range for the code diff (from first task commit to HEAD)
+</inputs>
+
+<process>
+
+<step name="compute_diff">
+Compute the diff from the plan's task commits.
+
+```bash
+FIRST_TASK_COMMIT=$(git log --oneline --grep="feat(${PHASE}-${PLAN}):" --grep="fix(${PHASE}-${PLAN}):" --grep="test(${PHASE}-${PLAN}):" --grep="refactor(${PHASE}-${PLAN}):" --reverse | head -1 | cut -d' ' -f1)
+```
+
+If FIRST_TASK_COMMIT is empty, exit with message: "No task commits found for ${PHASE}-${PLAN}, skipping code review."
+
+Otherwise, compute the full diff:
+
+```bash
+REVIEW_DIFF=$(git diff ${FIRST_TASK_COMMIT}^..HEAD)
+```
+
+Store REVIEW_DIFF for use by all review agents. Also store the file list:
+
+```bash
+CHANGED_FILES=$(git diff --name-only ${FIRST_TASK_COMMIT}^..HEAD)
+```
+
+Display:
+```
+Reviewing ${PHASE}-${PLAN} changes:
+  Files changed: $(echo "$CHANGED_FILES" | wc -l | tr -d ' ')
+  Diff size: $(echo "$REVIEW_DIFF" | wc -l | tr -d ' ') lines
+```
+</step>
+
+<step name="pass_1_foundational">
+**Pass 1: Foundational Review** -- Spawn 3 parallel Task() subagents.
+
+Each agent receives REVIEW_DIFF and CHANGED_FILES as input context.
+
+**Agent 1A: Correctness and Security**
+
+Review REVIEW_DIFF for:
+- Logic errors, off-by-one mistakes, incorrect conditionals
+- Null/undefined hazards, unhandled promise rejections
+- SQL injection, XSS, command injection
+- Auth bypass, missing authorization checks
+- Secret exposure (hardcoded keys, tokens, passwords)
+- Race conditions, deadlocks
+- Memory leaks, resource cleanup
+
+Output: Structured findings list with fields:
+- id: "1A-{N}"
+- severity: critical | high | medium | low
+- category: correctness | security
+- file: file path
+- line: line number or range
+- title: brief description
+- description: detailed explanation
+- suggestion: recommended fix
+
+---
+
+**Agent 1B: Standards and Patterns**
+
+Review REVIEW_DIFF against the plan's `<context>` file patterns for:
+- Naming conventions (variables, functions, files)
+- Import patterns (ordering, path style)
+- Error handling style (try/catch vs Result types vs error callbacks)
+- Code organization (module boundaries, file structure)
+- Type safety (any usage, missing types, loose generics)
+- Consistency with existing codebase patterns
+
+If a codebase/ map exists at ${project_root}/codebase/, reference CONVENTIONS.md for established patterns.
+
+Output: Structured findings list with fields:
+- id: "1B-{N}"
+- severity: critical | high | medium | low
+- category: standards | patterns
+- file, line, title, description, suggestion
+
+---
+
+**Agent 1C: Simplification and Over-engineering**
+
+Review REVIEW_DIFF for:
+- Unnecessary abstractions (wrapper classes with no added value)
+- Premature optimization (caching before profiling, complex algorithms for small data)
+- Dead code (unreachable branches, unused imports, commented-out code)
+- Overly clever solutions (prefer readable over clever)
+- Things that could be simpler (fewer indirection layers, simpler data structures)
+- YAGNI violations (features built but not needed by the plan)
+
+Output: Structured findings list with fields:
+- id: "1C-{N}"
+- severity: critical | high | medium | low
+- category: simplification | over-engineering
+- file, line, title, description, suggestion
+</step>
+
+<step name="pass_2_integration">
+**Pass 2: Integration Review** -- Spawn 3 parallel Task() subagents.
+
+Each agent receives REVIEW_DIFF, CHANGED_FILES, and all Pass 1 findings as input context.
+
+**Agent 2A: Fix Verification**
+
+For each auto-fixable finding from Pass 1 (severity medium or low with a clear fix), propose a concrete code change.
+
+Output: List of proposed fixes with fields:
+- finding_ref: reference to Pass 1 finding id (e.g., "1B-3")
+- file: file path
+- line_range: start-end lines
+- current_code: the code as it exists
+- proposed_fix: the corrected code
+- rationale: why this fix is safe
+- risk: low (formatting, naming) | medium (logic change)
+
+Only propose fixes where:
+- The change is unambiguous
+- Risk is low (no behavioral change) or the fix is clearly correct
+- The fix does not alter public API contracts
+
+---
+
+**Agent 2B: Integration and Flow**
+
+Review REVIEW_DIFF for:
+- Broken imports (referencing files that don't exist or wrong paths)
+- Missing exports (used by other files but not exported)
+- Type mismatches across file boundaries
+- API contract violations (calling functions with wrong signatures)
+- State management issues (stale state, missing synchronization)
+- Circular dependencies
+- Environment/config coupling issues
+
+Output: Structured findings list with fields:
+- id: "2B-{N}"
+- severity: critical | high | medium | low
+- category: integration | flow
+- file, line, title, description, suggestion
+
+---
+
+**Agent 2C: Test Coverage**
+
+Review REVIEW_DIFF for:
+- Untested branches (if/else without both paths tested)
+- Missing edge case tests (empty arrays, null inputs, boundary values)
+- Test assertions that don't verify behavior (testing implementation details)
+- Mocked-out critical paths (mocking the thing you're supposed to test)
+- Missing error path tests (only happy path tested)
+- Test naming that doesn't describe behavior
+
+Output: Structured findings list with fields:
+- id: "2C-{N}"
+- severity: critical | high | medium | low
+- category: test-coverage
+- file, line, title, description, suggestion
+</step>
+
+<step name="pass_3_final">
+**Pass 3: Final Review** -- Spawn 3 parallel Task() subagents.
+
+Each agent receives REVIEW_DIFF, CHANGED_FILES, and all findings from Pass 1 and Pass 2 as input context.
+
+**Agent 3A: Fresh Eyes**
+
+Re-read REVIEW_DIFF without bias from prior findings. Identify anything missed by the previous 6 agents. Focus on:
+- Subtle bugs that require understanding data flow across multiple functions
+- Edge cases in business logic
+- Assumptions that may not hold in production
+- Missing error messages or unhelpful error messages
+
+Output: Net-new findings only (deduplicated against all prior findings). Use fields:
+- id: "3A-{N}"
+- severity: critical | high | medium | low
+- category: fresh-eyes
+- file, line, title, description, suggestion
+
+---
+
+**Agent 3B: Production Readiness**
+
+Review for:
+- Error handling completeness (all external calls wrapped, all user inputs validated)
+- Logging adequacy (operations are logged, errors include context)
+- Graceful degradation (what happens when a dependency is down)
+- Configuration externalization (no hardcoded URLs, ports, credentials)
+- Deployment concerns (migration compatibility, backward compatibility)
+- Performance at scale (N+1 queries, unbounded loops, large payload handling)
+
+Output: Structured findings list with fields:
+- id: "3B-{N}"
+- severity: critical | high | medium | low
+- category: production-readiness
+- file, line, title, description, suggestion
+
+---
+
+**Agent 3C: Diff Sanity Check**
+
+Verify:
+- No debug code left in (console.log, console.debug, debugger statements)
+- No TODO/FIXME/HACK comments in production code
+- No commented-out code blocks (> 3 lines)
+- No accidental file inclusions (lock files, .env, build artifacts, node_modules)
+- Diff size is reasonable (flag if > 1000 lines changed in a single file)
+- No binary files accidentally committed
+- File permissions are correct
+
+Output: Structured findings list with fields:
+- id: "3C-{N}"
+- severity: critical | high | medium | low
+- category: sanity-check
+- file, line, title, description, suggestion
+</step>
+
+<step name="aggregate_findings">
+Merge all findings from all 3 passes (agents 1A, 1B, 1C, 2A, 2B, 2C, 3A, 3B, 3C).
+
+**Deduplication:**
+- Group by file + line range + category
+- If two findings reference the same code location with the same category, keep the one with higher severity
+- If same severity, keep the one with the more specific suggestion
+
+**Sort:**
+1. By severity: critical > high > medium > low
+2. Within severity: by file path alphabetically
+3. Within file: by line number ascending
+
+**Count totals:**
+- CRITICAL_COUNT
+- HIGH_COUNT
+- MEDIUM_COUNT
+- LOW_COUNT
+- TOTAL_COUNT
+
+Display:
+```
+Aggregated findings: ${TOTAL_COUNT} total
+  Critical: ${CRITICAL_COUNT}
+  High:     ${HIGH_COUNT}
+  Medium:   ${MEDIUM_COUNT}
+  Low:      ${LOW_COUNT}
+```
+</step>
+
+<step name="write_report">
+Create a persistent CODEREVIEW.md file at `${PHASE_DIR}/${PHASE}-${PLAN}-CODEREVIEW.md`.
+
+Store the file path as `CODEREVIEW_PATH` for use in subsequent steps:
+
+```bash
+CODEREVIEW_PATH="${PHASE_DIR}/${PHASE}-${PLAN}-CODEREVIEW.md"
+```
+
+Write the file with the following structure:
+
+**Frontmatter:**
+```yaml
+---
+phase: {PHASE}
+plan: {PLAN}
+status: pending  # Updated to "complete" after apply_auto_fixes
+timestamp: {ISO timestamp of when codereview started}
+stats:
+  total: {TOTAL_COUNT}
+  critical: {CRITICAL_COUNT}
+  high: {HIGH_COUNT}
+  medium: {MEDIUM_COUNT}
+  low: {LOW_COUNT}
+  auto_fixed: 0  # Updated after apply_auto_fixes
+  deviations_logged: 0  # Updated after log_deviations
+---
+```
+
+**Body content:**
+
+```markdown
+# Code Review: {PHASE}-{PLAN}
+
+## Summary
+
+| Metric | Count |
+|--------|-------|
+| Total findings | {TOTAL_COUNT} |
+| Critical | {CRITICAL_COUNT} |
+| High | {HIGH_COUNT} |
+| Medium | {MEDIUM_COUNT} |
+| Low | {LOW_COUNT} |
+
+## Pass 1: Foundational Review
+
+### Critical
+{findings from 1A/1B/1C with severity critical, formatted as:}
+**{id}: {title}** -- `{file}:{line}`
+{description}
+> Suggestion: {suggestion}
+
+### High
+{same format}
+
+### Medium
+{same format}
+
+### Low
+{same format}
+
+## Pass 2: Integration Review
+
+{Same structure for 2A/2B/2C findings. Note: 2A proposed fixes are listed under their original finding severity, with a "(auto-fixable)" tag if they qualify.}
+
+## Pass 3: Final Review
+
+{Same structure for 3A/3B/3C findings}
+
+## Auto-Fix Results
+
+_Pending -- will be updated after auto-fix step._
+
+## Deviations Logged
+
+_Pending -- will be updated after deviation logging._
+```
+
+For each pass section, if no findings exist for a severity level, omit that severity heading. If no findings exist for an entire pass, write: "No findings."
+</step>
+
+<step name="apply_auto_fixes">
+Take the proposed fixes from Agent 2A.
+
+**Apply ONLY fixes that meet ALL criteria:**
+- Severity is medium or low
+- Single-line or small-scope changes (< 5 lines)
+- No behavioral change (formatting, naming, simple null checks, missing return types, import ordering)
+- Risk rated as "low" by Agent 2A
+
+**Process:**
+1. For each qualifying fix:
+   a. Read the target file
+   b. Verify the current_code matches what is actually in the file
+   c. Apply the proposed_fix
+   d. Record the change
+
+2. After all fixes applied, run any available verify commands from the PLAN.md tasks to confirm nothing breaks:
+   ```bash
+   # Extract verify commands from PLAN.md
+   grep -A 5 "<automated>" ${PLAN_PATH} | grep -v "automated" | head -10
+   ```
+
+3. If a fix breaks verification:
+   - Revert that specific fix
+   - Remove it from the applied list
+   - Log: "Reverted fix {finding_ref}: broke verification"
+
+4. Stage all successful fixes and commit:
+
+```bash
+git add [fixed files]
+git commit -m "fix(${PHASE}-${PLAN}): codereview auto-fixes
+
+- [list each fix applied, one per bullet]
+
+Co-Authored-By: Claude Code Review <noreply@anthropic.com>"
+```
+
+If no fixes qualify or all were reverted, skip the commit. Set AUTO_FIX_COMMIT to the commit hash or "none".
+
+Record:
+- FIXES_APPLIED: count of successful fixes
+- FIXES_REVERTED: count of reverted fixes
+- AUTO_FIX_COMMIT: commit hash or "none"
+
+**Update CODEREVIEW.md with auto-fix results:**
+
+Read `${CODEREVIEW_PATH}`. Replace the "## Auto-Fix Results" section content:
+
+If fixes were applied:
+```markdown
+## Auto-Fix Results
+
+| Finding | File | Fix | Status |
+|---------|------|-----|--------|
+| {finding_ref} | {file}:{line_range} | {rationale} | Applied |
+{... one row per fix applied ...}
+{... if any reverted:}
+| {finding_ref} | {file}:{line_range} | {rationale} | Reverted: {reason} |
+
+**Applied:** {FIXES_APPLIED} | **Reverted:** {FIXES_REVERTED} | **Commit:** {AUTO_FIX_COMMIT}
+```
+
+If no fixes qualified:
+```markdown
+## Auto-Fix Results
+
+No fixes qualified for auto-application (all findings were critical/high severity or required behavioral changes).
+```
+
+Update the frontmatter: set `stats.auto_fixed` to `{FIXES_APPLIED}`.
+
+Include CODEREVIEW.md in the auto-fix commit by adding it to the staged files:
+
+Change the existing `git add [fixed files]` to also include CODEREVIEW.md:
+```bash
+git add [fixed files] ${CODEREVIEW_PATH}
+```
+
+If no auto-fixes were applied (commit skipped), commit CODEREVIEW.md alone:
+```bash
+git add ${CODEREVIEW_PATH}
+git commit -m "docs(${PHASE}-${PLAN}): codereview report
+
+Co-Authored-By: Claude Code Review <noreply@anthropic.com>"
+```
+</step>
+
+<step name="log_deviations">
+For CRITICAL and HIGH findings that were NOT auto-fixed:
+
+**Do NOT prompt the user.** Non-interactive mode per design decision.
+
+Instead, append each as a deviation entry to the SUMMARY.md that was already created at ${PHASE_DIR}/${PHASE}-${PLAN}-SUMMARY.md.
+
+Read the existing SUMMARY.md. Find the `## Deviations from Plan` section. Append after the existing deviation entries (or after "None - plan executed exactly as written" if no prior deviations):
+
+For each critical/high finding:
+```
+**[Codereview - {severity}] {title}** -- File: {file}:{line} | Finding: {description} | Suggested fix: {suggestion}
+```
+
+Add a new section after `## Deviations from Plan`:
+
+```markdown
+## Code Review
+
+| Metric | Count |
+|--------|-------|
+| Total findings | {TOTAL_COUNT} |
+| Critical | {CRITICAL_COUNT} |
+| High | {HIGH_COUNT} |
+| Medium | {MEDIUM_COUNT} |
+| Low | {LOW_COUNT} |
+| Auto-fixed | {FIXES_APPLIED} |
+| Logged as deviations | {DEVIATIONS_LOGGED} |
+
+Auto-fix commit: {AUTO_FIX_COMMIT}
+```
+
+Where DEVIATIONS_LOGGED = count of critical + high findings that were not auto-fixed.
+
+**Update CODEREVIEW.md with deviations logged:**
+
+Read `${CODEREVIEW_PATH}`. Replace the "## Deviations Logged" section content:
+
+If deviations were logged:
+```markdown
+## Deviations Logged
+
+{DEVIATIONS_LOGGED} critical/high findings logged as deviations to SUMMARY.md:
+
+| ID | Severity | Title | File |
+|----|----------|-------|------|
+| {id} | {severity} | {title} | {file}:{line} |
+{... one row per deviation ...}
+```
+
+If no deviations:
+```markdown
+## Deviations Logged
+
+No critical/high findings to log as deviations.
+```
+
+Update the frontmatter: set `stats.deviations_logged` to `{DEVIATIONS_LOGGED}` and set `status` to `complete`.
+
+Stage the updated CODEREVIEW.md:
+```bash
+git add ${CODEREVIEW_PATH}
+```
+(It will be included in the next commit -- either the metadata commit from execute-plan or amend.)
+</step>
+
+<step name="report_completion">
+Display summary box:
+
+```
+------------------------------------------------------------
+ CODEREVIEW COMPLETE: ${PHASE}-${PLAN}
+------------------------------------------------------------
+
+ Pass 1 (Foundation):  {N} findings
+ Pass 2 (Integration): {N} findings  ({M} auto-fixable)
+ Pass 3 (Final):       {N} findings
+
+ Total: {T} | Auto-fixed: {F} | Logged as deviations: {D}
+ Commit: {AUTO_FIX_COMMIT}
+------------------------------------------------------------
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Diff computed from plan's task commits
+- [ ] Pass 1: 3 parallel agents (Correctness/Security, Standards/Patterns, Simplification)
+- [ ] Pass 2: 3 parallel agents (Fix Verification, Integration/Flow, Test Coverage)
+- [ ] Pass 3: 3 parallel agents (Fresh Eyes, Production Readiness, Diff Sanity Check)
+- [ ] Findings aggregated, deduplicated, sorted by severity
+- [ ] Auto-fixes applied for qualifying medium/low findings (< 5 lines, no behavioral change)
+- [ ] Auto-fix commit uses format: fix({phase}-{plan}): codereview auto-fixes
+- [ ] CRITICAL/HIGH findings logged as deviations to SUMMARY.md (non-interactive)
+- [ ] Code Review section added to SUMMARY.md with metrics
+- [ ] CODEREVIEW.md created at ${PHASE_DIR}/${PHASE}-${PLAN}-CODEREVIEW.md with findings, auto-fix results, and deviation log
+- [ ] Completion report displayed
+</success_criteria>