ocak 0.4.0 → 0.5.0

data/lib/ocak/state_management.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Ocak
+  # State accumulation and reporting logic extracted from PipelineExecutor.
+  # Includers must provide @config, @logger instance variables and pipeline_state, current_branch methods.
+  module StateManagement
+    StepContext = Struct.new(:issue_number, :idx, :role, :result, :state, :logger, :chdir)
+
+    def record_step_result(ctx, mutex: nil)
+      sync(mutex) { accumulate_state(ctx) }
+      save_step_progress(ctx)
+      write_step_output(ctx.issue_number, ctx.idx, ctx.role, ctx.result.output)
+      post_step_completion_comment(ctx.issue_number, ctx.role, ctx.result)
+
+      check_step_failure(ctx) || check_cost_budget(ctx.state, ctx.logger)
+    end
+
+    def accumulate_state(ctx)
+      update_pipeline_state(ctx.role, ctx.result, ctx.state)
+      ctx.state[:completed_steps] << ctx.idx
+      ctx.state[:steps_run] += 1
+      ctx.state[:total_cost] += ctx.result.cost_usd.to_f
+      ctx.state[:step_results][ctx.role] = ctx.result
+    end
+
+    def sync(mutex, &)
+      if mutex
+        mutex.synchronize(&)
+      else
+        yield
+      end
+    end
+
+    def save_step_progress(ctx)
+      pipeline_state.save(ctx.issue_number,
+                          completed_steps: ctx.state[:completed_steps],
+                          worktree_path: ctx.chdir,
+                          branch: current_branch(ctx.chdir, logger: ctx.logger))
+    end
+
+    def write_step_output(issue_number, idx, agent, output)
+      return if output.to_s.empty?
+      return unless issue_number.to_s.match?(/\A\d+\z/)
+
+      safe_agent = agent.to_s.gsub(/[^a-zA-Z0-9_-]/, '')
+      dir = File.join(@config.project_dir, '.ocak', 'logs', "issue-#{issue_number}")
+      FileUtils.mkdir_p(dir)
+      File.write(File.join(dir, "step-#{idx}-#{safe_agent}.md"), output)
+    rescue StandardError => e
+      @logger&.debug("Step output write failed: #{e.message}")
+      nil
+    end
+
+    def check_step_failure(ctx)
+      return nil if ctx.result.success? || !%w[implement merge].include?(ctx.role)
+
+      ctx.logger.error("#{ctx.role} failed")
+      { success: false, phase: ctx.role, output: ctx.result.output }
+    end
+
+    def check_cost_budget(state, logger)
+      return nil unless @config.cost_budget && state[:total_cost] > @config.cost_budget
+
+      cost = format('%.2f', state[:total_cost])
+      budget = format('%.2f', @config.cost_budget)
+      logger.error("Cost budget exceeded ($#{cost}/$#{budget})")
+      { success: false, phase: 'budget', output: "Cost budget exceeded: $#{cost}" }
+    end
+
+    def update_pipeline_state(role, result, state)
+      case role
+      when 'review', 'verify', 'security', 'audit'
+        state[:last_review_output] = result.output
+        if role == 'audit'
+          state[:audit_output] = result.output
+          state[:audit_blocked] = !result.success? || result.output.to_s.match?(/BLOCK|🔴/)
+        end
+      when 'fix'
+        state[:had_fixes] = true
+        state[:last_review_output] = nil
+      when 'implement'
+        state[:last_review_output] = nil
+      end
+    end
+
+    def log_cost_summary(total_cost, logger)
+      return if total_cost.zero?
+
+      budget = @config.cost_budget
+      budget_str = budget ? " / $#{format('%.2f', budget)} budget" : ''
+      logger.info("Pipeline cost: $#{format('%.4f', total_cost)}#{budget_str}")
+    end
+
+    def save_report(report, issue_number, success:, failed_phase: nil)
+      report.finish(success: success, failed_phase: failed_phase)
+      report.save(issue_number, project_dir: @config.project_dir)
+    rescue StandardError => e
+      @logger&.debug("Report save failed: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/ocak/step_execution.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ocak
+  # Individual step execution logic extracted from PipelineExecutor.
+  # Includers must provide @config, @skip_steps, post_step_comment, build_step_prompt methods.
+  module StepExecution
+    def run_single_step(step, idx, issue_number, state, logger:, claude:, chdir:, mutex: nil) # rubocop:disable Metrics/ParameterLists
+      role = step[:role].to_s
+      agent = step[:agent].to_s
+
+      return nil if handle_already_completed(idx, role, @skip_steps, logger)
+
+      reason = skip_reason(step, state)
+      if reason
+        logger.info("Skipping #{role} — #{reason}")
+        record_skipped_step(issue_number, state, idx, agent, role, reason)
+        return nil
+      end
+
+      result = execute_step(step, issue_number, state[:last_review_output], logger: logger, claude: claude,
+                                                                            chdir: chdir)
+      state[:report].record_step(index: idx, agent: agent, role: role, status: 'completed', result: result)
+      ctx = StateManagement::StepContext.new(issue_number, idx, role, result, state, logger, chdir)
+      record_step_result(ctx, mutex: mutex)
+    end
+
+    def handle_already_completed(idx, role, skip_steps, logger)
+      return false unless skip_steps.include?(idx)
+
+      logger.info("Skipping #{role} (already completed)")
+      true
+    end
+
+    def record_skipped_step(issue_number, state, idx, agent, role, reason)
+      post_step_comment(issue_number, "⏭️ **Skipping #{role}** — #{reason}")
+      state[:report].record_step(index: idx, agent: agent, role: role, status: 'skipped', skip_reason: reason)
+      state[:steps_skipped] += 1
+    end
+
+    def execute_step(step, issue_number, review_output, logger:, claude:, chdir:)
+      agent = step[:agent].to_s
+      role = step[:role].to_s
+      logger.info("--- Phase: #{role} (#{agent}) ---")
+      post_step_comment(issue_number, "🔄 **Phase: #{role}** (#{agent})")
+      prompt = build_step_prompt(role, issue_number, review_output)
+      opts = { chdir: chdir }
+      opts[:model] = step[:model].to_s if step[:model]
+      claude.run_agent(agent.tr('_', '-'), prompt, **opts)
+    end
+
+    def skip_reason(step, state)
+      condition = step[:condition]
+
+      return 'merge handled by MergeManager' if step[:role].to_s == 'merge' && @skip_merge
+      return 'audit found blocking issues' if step[:role].to_s == 'merge' && @config.audit_mode && state[:audit_blocked]
+      return 'manual review mode' if step[:role].to_s == 'merge' && @config.manual_review
+      return 'fast-track issue (simple complexity)' if step[:complexity] == 'full' && state[:complexity] == 'simple'
+      if condition == 'has_findings' && !state[:last_review_output]&.include?('🔴')
+        return 'no blocking findings from review'
+      end
+      return 'no fixes were made' if condition == 'had_fixes' && !state[:had_fixes]
+
+      nil
+    end
+  end
+end

data/lib/ocak/templates/agents/auditor.md.erb

@@ -18,6 +18,7 @@ You audit changed files as a pre-merge gate. You are read-only. Focus ONLY on fi
 git diff main --name-only
 ```
 3. Read every changed file in full
+4. Read the corresponding test files for each changed file
 
 ## Audit Checklist
 
@@ -55,6 +56,7 @@ For each changed file, check:
 - Are there tests for the changed code?
 - Do tests cover error paths?
 - Do tests cover edge cases?
+- Do tests assert specific outcomes, not just "doesn't crash"?
 
 ### Data
 - Potential N+1 queries or unbounded queries
@@ -66,22 +68,49 @@ For each changed file, check:
 ```
 ## Audit Report
 
-### Critical Issues (BLOCK if found)
-[List any critical security or correctness issues. Use the word BLOCK for critical items.]
+**Files audited**: N
 
-### Warnings
-[Pattern violations, missing tests, minor issues]
+### Findings
 
-### Observations
-[Non-blocking notes and suggestions]
+#### 🔴 Critical — [Title]
+**File**: `path/to/file:42`
+**Category**: [Security | Pattern | Error Handling | Test Coverage | Data]
+**Issue**: [What's wrong]
+**Impact**: [What could go wrong]
+**Recommendation**: [Exact fix]
 
-### Files Audited
-- [file]: [status]
+#### 🟡 Warning — [Title]
+**File**: `path/to/file:78`
+**Category**: [category]
+**Issue**: [What's wrong]
+**Recommendation**: [How to fix]
+
+#### 🟢 Good — [Title]
+[What was done well]
+
+### Test Coverage Summary
+
+| Changed File | Test File | Methods Tested | Missing Coverage |
+|-------------|-----------|---------------|-----------------|
+| `path/to/file` | `path/to/file_test` | 4/5 | `edge_case_method` |
+| `path/to/other` | ❌ None | 0/3 | All methods |
+
+### Verdict
+
+**PASS** — No critical findings. Safe to merge.
+or
+**PASS WITH WARNINGS** — N warnings found. Review recommended but not blocking.
+or
+**BLOCK** — N critical findings. Must fix before merge. [List the critical items]
 ```
 
-Use the word **BLOCK** for any finding that should prevent merging. Only use BLOCK for:
+## Blocking Rules
+
+The auditor blocks merge (outputs "BLOCK" verdict) ONLY for:
 - Authentication/authorization bypass
 - Injection vulnerabilities
 - Secrets exposure
 - Data corruption risks
 - Critical missing tests for dangerous operations
+
+All other findings are warnings — reported but not blocking.

data/lib/ocak/templates/agents/implementer.md.erb

@@ -11,10 +11,11 @@ You implement GitHub issues. The issue is your single source of truth — everyt
 
 ## Before You Start
 
-1. Read the issue via `gh issue view <number> --json title,body,labels`
-2. Read `CLAUDE.md` for project conventions
-3. Read every file listed in the issue's "Relevant files" and "Patterns to Follow" sections
-4. Understand the existing patterns before writing any code
+1. Check branch state: `git log main..HEAD --oneline` and `git diff main --stat` — work may already be partially done
+2. Read the issue via `gh issue view <number> --json title,body,labels`
+3. Read `CLAUDE.md` for project conventions
+4. Read every file listed in the issue's "Relevant files" and "Patterns to Follow" sections
+5. When writing new code, find the closest existing example first (neighboring file in the same directory/namespace) and mirror its structure exactly
 
 ## Implementation Rules
 
@@ -103,6 +104,20 @@ You implement GitHub issues. The issue is your single source of truth — everyt
 - Do NOT add comments, docstrings, or type annotations to code you didn't write
 - Match the existing code style exactly — look at neighboring files
 
+### Scope Discipline (CRITICAL)
+
+You MUST NOT modify code outside the issue's scope. This is the #1 source of pipeline regressions. Specifically:
+
+- **Do NOT change existing method signatures** unless the issue requires it
+- **Do NOT change error messages or string literals** unless the issue requires it
+- **Do NOT change query logic** (e.g., operators, sort order) unless the issue requires it
+- **Do NOT change data types** unless the issue requires it
+- **Do NOT delete existing tests** — only add new ones or modify tests for code you changed
+- **Do NOT remove security protections** (rate limiting, input validation, access checks)
+- **Do NOT change configuration files** unless the issue requires it
+
+Before each commit, run `git diff main --stat` and verify EVERY changed file is justified by the issue's acceptance criteria. If a file appears that shouldn't be there, revert it with `git checkout main -- <file>`.
+
 ## Testing Requirements
 
 Write tests for every acceptance criterion in the issue:
@@ -153,21 +168,30 @@ Combine related changes: a class and its tests go in one commit, not two.
 - If a lint fix is needed for already-committed code, make a separate `style` commit
 - Keep commits small and reviewable — if a commit touches 10+ files across unrelated areas, split it
 
+## When Stuck
+
+- **Test won't pass after 2 attempts**: Re-read the full source file and the full test file. The answer is usually in existing code you haven't read yet.
+- **Can't find the right pattern**: Look at the nearest neighboring file in the same directory — don't invent a new approach.
+- **Unsure what a method does**: Read the method's test file, not just its source.
+- **Don't iterate on a broken approach**: If your approach fails twice, switch to a different strategy.
+
 ## Verification Checklist
 
 After implementation, run these commands and fix ALL failures before finishing:
 
+1. **Scope check**: `git diff main --stat` — verify every file is justified by the issue. Revert any unrelated changes.
+2. **Deleted test check**: `git diff main` — verify you haven't deleted any existing test methods. If you have, restore them.
 <%- if test_command -%>
-1. **Tests**: `<%= test_command %>`
+3. **Tests**: `<%= test_command %>`
 <%- end -%>
 <%- if lint_command -%>
-2. **Lint**: `<%= lint_command %>`
+4. **Lint**: `<%= lint_command %>`
 <%- end -%>
 <%- if format_command -%>
-3. **Format**: `<%= format_command %>`
+5. **Format**: `<%= format_command %>`
 <%- end -%>
 <%- security_commands.each_with_index do |cmd, i| -%>
-<%= i + 4 %>. **Security**: `<%= cmd %>`
+<%= i + 6 %>. **Security**: `<%= cmd %>`
 <%- end -%>
 
 Do NOT stop until all commands pass. If a test fails, read the error, fix the code, and re-run. Maximum 5 fix attempts per command — if still failing after 5 attempts, report what's failing and why.

data/lib/ocak/templates/agents/merger.md.erb

@@ -13,21 +13,20 @@ You handle the git workflow for completed issues.
 
 ### 1. Verify Readiness
 
-Before creating a PR, verify:
+Tests and linters were already verified by the implementer. Do NOT re-run the full test suite — it wastes time and money.
 
+Only re-run tests if you had to resolve merge conflicts or edit files:
 ```bash
 <%- if test_command -%>
-# Tests pass
+# ONLY after resolving merge conflicts:
 <%= test_command %>
 <%- end -%>
-
 <%- if lint_command -%>
-# Linter passes
 <%= lint_command %>
 <%- end -%>
 ```
 
-If anything fails, STOP and report the failures. Do not create a PR with failing checks.
+If anything fails after conflict resolution, STOP and report the failures. Do not create a PR with failing checks.
 
 ### 2. Create Pull Request
 
@@ -87,6 +86,13 @@ gh pr merge --merge --delete-branch
 gh issue close <number> --comment "Implemented in PR #<pr-number>"
 ```
 
+### 5. Clean Up
+
+```bash
+git checkout main
+git pull origin main
+```
+
 ## Output
 
 ```
@@ -94,4 +100,5 @@ gh issue close <number> --comment "Implemented in PR #<pr-number>"
 - PR: #<number> (<url>)
 - Issue: #<number> closed
 - Branch: <name> (deleted)
+- Merge commit: <sha>
 ```

data/lib/ocak/templates/agents/pipeline.md.erb

@@ -43,6 +43,10 @@ git diff main --stat
 git diff main
 ```
 
+**Scope check**: Verify EVERY changed file is justified by the issue's acceptance criteria. If a file appears that shouldn't be there, revert it with `git checkout main -- <file>`.
+
+**Deleted test check**: Verify you haven't deleted any existing test methods. If you have, restore them.
+
 For each acceptance criterion, verify:
 - Is it implemented correctly?
 - Is it tested?

data/lib/ocak/templates/agents/reviewer.md.erb

@@ -85,8 +85,8 @@ Rate each finding:
 [What was done well]
 
 ### Acceptance Criteria Check
-- [ ] Criterion 1: implemented and tested / missing [details]
-- [ ] Criterion 2: ...
+- [ ] Criterion 1: ✅ Implemented and tested / ❌ Missing [details]
+- [ ] Criterion 2: ✅ / ❌
 
 ### Test Coverage
 - [List any untested paths or missing edge cases]

data/lib/ocak/templates/agents/security_reviewer.md.erb

@@ -10,6 +10,10 @@ model: sonnet
 
 You perform security-focused code review. You are read-only.
 
+## Focus
+
+You run AFTER the code reviewer. Focus on security-specific concerns that a general code reviewer would miss. Do NOT repeat general code quality findings (missing tests, naming, patterns). Your value is catching auth bypasses, injection vectors, data exposure, and business logic integrity issues that require security expertise.
+
 ## Setup
 
 1. Read CLAUDE.md for auth architecture and conventions
@@ -64,6 +68,13 @@ You perform security-focused code review. You are read-only.
 - [ ] Logs don't contain PII or secrets
 - [ ] No secrets in code (API keys, passwords, tokens)
 
+### Business Logic Integrity
+
+- [ ] Domain invariants maintained (e.g., balances sum correctly, state transitions are valid)
+- [ ] Calculations use appropriate precision (no floating-point for monetary/exact values)
+- [ ] Race conditions handled where concurrent access is possible (database locks, transactions)
+- [ ] Multi-tenant data properly scoped — no cross-tenant access paths
+
 ### Dependencies
 
 Run and report results of:

data/lib/ocak/templates/ocak.yml.erb

@@ -27,6 +27,12 @@ stack:
 <%- end -%>
 <%- end -%>
 
+# Issue backend — 'github' (default) or 'local'
+# Local mode stores issues as files in .ocak/issues/ (no gh CLI needed for issues).
+# Auto-detected: if .ocak/issues/ contains .md files, local mode is used automatically.
+# issues:
+#   backend: local
+
 # Pipeline settings
 pipeline:
   max_parallel: 5
@@ -57,29 +63,38 @@ labels:
 steps:
   - agent: implementer
     role: implement
+    model: sonnet
   - agent: reviewer
     role: review
+    model: opus
   - agent: implementer
     role: fix
     condition: has_findings
+    model: sonnet
   - agent: reviewer
     role: verify
     condition: had_fixes
+    model: opus
   - agent: security_reviewer
     role: security
+    model: sonnet
     complexity: full          # skipped for simple issues and --fast mode
   - agent: implementer
     role: fix
     condition: has_findings
     complexity: full          # skipped for simple issues
+    model: sonnet
   - agent: documenter
     role: document
     complexity: full          # skipped for simple issues
+    model: sonnet
   - agent: auditor
     role: audit
     complexity: full          # skipped for simple issues
+    model: sonnet
   - agent: merger
     role: merge
+    model: sonnet
 
 # Agent file paths — override to use custom agents
 agents:

data/lib/ocak/verification.rb

@@ -52,7 +52,12 @@ module Ocak
     end
 
     def run_scoped_lint(logger, chdir:)
-      changed_stdout, = Open3.capture3('git', 'diff', '--name-only', 'main', chdir: chdir)
+      changed_stdout, stderr, status = Open3.capture3('git', 'diff', '--name-only', 'main', chdir: chdir)
+      unless status.success?
+        logger&.warn("Scoped lint skipped — git diff failed: #{stderr[0..200]}")
+        return nil
+      end
+
       changed_files = changed_stdout.lines.map(&:strip).reject(&:empty?)
 
       extensions = lint_extensions_for(@config.language)

data/lib/ocak/worktree_manager.rb

@@ -16,6 +16,8 @@ module Ocak
 
     def create(issue_number, setup_command: nil)
       @mutex.synchronize do
+        raise ArgumentError, "Invalid issue number: #{issue_number}" unless issue_number.to_s.match?(/\A\d+\z/)
+
         FileUtils.mkdir_p(@worktree_base)
 
         branch = "auto/issue-#{issue_number}-#{SecureRandom.hex(4)}"

data/lib/ocak.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Ocak
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 
   def self.root
     File.expand_path('..', __dir__)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ocak
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Clay Harmon
@@ -36,35 +36,51 @@ files:
 - bin/ocak
 - lib/ocak.rb
 - lib/ocak/agent_generator.rb
+- lib/ocak/batch_processing.rb
 - lib/ocak/claude_runner.rb
 - lib/ocak/cli.rb
+- lib/ocak/command_runner.rb
 - lib/ocak/commands/audit.rb
 - lib/ocak/commands/clean.rb
 - lib/ocak/commands/debt.rb
 - lib/ocak/commands/design.rb
 - lib/ocak/commands/hiz.rb
 - lib/ocak/commands/init.rb
+- lib/ocak/commands/issue/close.rb
+- lib/ocak/commands/issue/create.rb
+- lib/ocak/commands/issue/edit.rb
+- lib/ocak/commands/issue/list.rb
+- lib/ocak/commands/issue/view.rb
 - lib/ocak/commands/resume.rb
 - lib/ocak/commands/run.rb
 - lib/ocak/commands/status.rb
 - lib/ocak/config.rb
 - lib/ocak/failure_reporting.rb
 - lib/ocak/git_utils.rb
+- lib/ocak/instance_builders.rb
+- lib/ocak/issue_backend.rb
 - lib/ocak/issue_fetcher.rb
+- lib/ocak/local_issue_fetcher.rb
+- lib/ocak/local_merge_manager.rb
 - lib/ocak/logger.rb
 - lib/ocak/merge_manager.rb
 - lib/ocak/merge_orchestration.rb
 - lib/ocak/monorepo_detector.rb
+- lib/ocak/parallel_execution.rb
 - lib/ocak/pipeline_executor.rb
 - lib/ocak/pipeline_runner.rb
 - lib/ocak/pipeline_state.rb
 - lib/ocak/planner.rb
 - lib/ocak/process_registry.rb
 - lib/ocak/process_runner.rb
+- lib/ocak/project_key.rb
 - lib/ocak/reready_processor.rb
 - lib/ocak/run_report.rb
+- lib/ocak/shutdown_handling.rb
 - lib/ocak/stack_detector.rb
+- lib/ocak/state_management.rb
 - lib/ocak/step_comments.rb
+- lib/ocak/step_execution.rb
 - lib/ocak/stream_parser.rb
 - lib/ocak/templates/agents/auditor.md.erb
 - lib/ocak/templates/agents/documenter.md.erb