plan_driven 0.1.0

data/lib/plan_driven/guards/ticket_normalizer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Guards
+    # Deterministic fixes applied to drafted tickets before they're checked. Anything that has
+    # exactly one right answer is corrected here and reported, instead of being sent back to the
+    # model for another attempt.
+    class TicketNormalizer
+      TITLE_PREFIX = { "migration" => "Migration: ", "backfill" => "Data migration: " }.freeze
+      KIND_ALIASES = {
+        "schema" => "migration", "db" => "migration", "database" => "migration",
+        "data_migration" => "backfill", "data" => "backfill", "feature" => "code", "application" => "code",
+        "read_switch" => "switch", "contract" => "cleanup", "removal" => "cleanup", "documentation" => "docs"
+      }.freeze
+
+      def initialize(tickets, config: PlanDriven.configuration)
+        @tickets = Array(tickets).map { |ticket| ticket.to_h.transform_keys(&:to_s) }
+        @config = config
+      end
+
+      def call(report)
+        keys = {}
+        tickets = @tickets.each_with_index.map { |ticket, index| normalize(ticket, index, keys, report) }
+        remap_dependencies(tickets, keys)
+        tickets
+      end
+
+      private
+
+      def normalize(ticket, index, keys, report)
+        key = "T#{index + 1}"
+        keys[ticket["key"].to_s] = key unless ticket["key"].to_s.empty?
+        ticket.merge!("key" => key, "position" => index)
+        ticket["kind"] = kind(ticket["kind"], key, report)
+        ticket["type"] = ticket["type"].to_s.upcase.presence || "TASK"
+        ticket["title"] = title(ticket["title"].to_s.strip, ticket["kind"], key, report)
+        ticket["estimate"] = estimate(ticket["estimate"], key, report)
+        normalize_lists(ticket)
+      end
+
+      def normalize_lists(ticket)
+        ticket["acceptance_criteria"] = list(ticket["acceptance_criteria"])
+        ticket["depends_on"] = list(ticket["depends_on"]).map(&:upcase)
+        ticket["touches"] = list(ticket["touches"]).map { |table| table.downcase.delete("`") }
+        ticket
+      end
+
+      def kind(value, label, report)
+        value = value.to_s.downcase.strip.tr(" -", "__")
+        return value if Ticket::KINDS.include?(value)
+
+        mapped = KIND_ALIASES[value] || "code"
+        report.fix("#{label}: kind \"#{value}\" read as #{mapped}") unless value.empty?
+        mapped
+      end
+
+      def title(value, kind, label, report)
+        prefix = TITLE_PREFIX[kind]
+        return value if prefix.nil? || value.start_with?(prefix)
+
+        stripped = value.sub(/\A(data\s+)?migration:\s*/i, "")
+        report.fix("#{label}: title prefixed with \"#{prefix.strip}\"")
+        "#{prefix}#{stripped}"
+      end
+
+      def estimate(value, label, report)
+        number = value.to_s[/\d+/]&.to_i
+        return if number.nil?
+
+        scale = @config.estimate_scale
+        return number if scale.include?(number)
+
+        rounded = scale.find { |point| point >= number } || scale.last
+        report.fix("#{label}: estimate #{number} rounded up to #{rounded}, the next point on the scale")
+        rounded
+      end
+
+      def list(value)
+        items = value.is_a?(Array) ? value : value.to_s.split(/\n|;/)
+        items.map { |item| item.to_s.strip.sub(/\A[-*\u2022]\s*/, "") }.reject(&:empty?)
+      end
+
+      def remap_dependencies(tickets, keys)
+        tickets.each do |ticket|
+          ticket["depends_on"] = ticket["depends_on"].map { |key| keys.fetch(key, key) }.uniq
+        end
+      end
+    end
+  end
+end

data/lib/plan_driven/guards.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Rules enforced in Ruby rather than asked for in a prompt. A prompt line costs tokens on every
+  # call and a model can ignore it; a guard runs every time and says exactly what's wrong.
+  module Guards
+    # Errors block the next phase. Warnings are shown and recorded, and a human decides.
+    class Report
+      attr_reader :errors, :warnings, :fixes, :passes
+
+      def initialize
+        @errors = []
+        @warnings = []
+        @fixes = []
+        @passes = []
+      end
+
+      def error(message) = errors << message
+      def warning(message) = warnings << message
+      def fix(message) = fixes << message
+      # What was checked and found fine, so a reviewer can see what the guard looked at.
+      def pass(message) = passes << message
+
+      def ok?
+        errors.empty?
+      end
+
+      def merge!(other)
+        errors.concat(other.errors)
+        warnings.concat(other.warnings)
+        fixes.concat(other.fixes)
+        passes.concat(other.passes)
+        self
+      end
+
+      def to_h
+        { "errors" => errors, "warnings" => warnings, "fixes" => fixes, "passes" => passes }
+      end
+
+      def self.from_h(hash)
+        report = new
+        hash ||= {}
+        report.errors.concat(Array(hash["errors"]))
+        report.warnings.concat(Array(hash["warnings"]))
+        report.fixes.concat(Array(hash["fixes"]))
+        report.passes.concat(Array(hash["passes"]))
+        report
+      end
+    end
+  end
+end
+
+require_relative "guards/plan_guard"
+require_relative "guards/migration_guard"
+require_relative "guards/ticket_normalizer"
+require_relative "guards/ticket_guard"
+require_relative "guards/pr_guard"

data/lib/plan_driven/http.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module PlanDriven
+  # A small JSON client over net/http. The transport is swappable so the specs never touch the
+  # network: anything responding to `call(method, url, headers, body)` and returning
+  # `[status, body_string]` works.
+  class HTTP
+    Response = Struct.new(:status, :body, keyword_init: true) do
+      def success?
+        status.between?(200, 299)
+      end
+
+      def json
+        body.to_s.strip.empty? ? {} : JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
+    class << self
+      attr_writer :transport
+
+      def transport
+        @transport ||= method(:net_http)
+      end
+
+      def reset!
+        @transport = nil
+      end
+
+      def request(method, url, headers: {}, body: nil, timeout: 60)
+        payload = body.nil? || body.is_a?(String) ? body : JSON.generate(body)
+        status, text = transport.call(method.to_s.upcase, url, headers, payload, timeout)
+        Response.new(status: status.to_i, body: text.to_s)
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise ProviderError, "#{URI(url).host} did not respond within #{timeout}s"
+      rescue SocketError, SystemCallError => e
+        raise ProviderError, "Could not reach #{URI(url).host}: #{e.message}"
+      end
+
+      private
+
+      def net_http(method, url, headers, body, timeout)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = timeout
+        request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+        request.body = body if body
+        response = http.request(request)
+        [response.code.to_i, response.body]
+      end
+    end
+  end
+end

data/lib/plan_driven/json_reply.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Models wrap JSON in prose or code fences often enough that parsing has to be forgiving,
+  # and exact enough that anything else is reported back to the model as an error.
+  module JsonReply
+    FENCE = /```(?:json)?\s*(.*?)```/m
+
+    module_function
+
+    def parse(text)
+      candidates(text.to_s).each do |candidate|
+        return JSON.parse(candidate)
+      rescue JSON::ParserError
+        next
+      end
+      raise InvalidResponseError, "the reply wasn't valid JSON"
+    end
+
+    def candidates(text)
+      fenced = text.scan(FENCE).flatten
+      braces = text[text.index("{").to_i..(text.rindex("}") || -1)]
+      [text, *fenced, braces].compact.map(&:strip).uniq
+    end
+  end
+end

data/lib/plan_driven/llm.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # One call: a system prompt and messages in, text out. Planning is where a stronger model pays
+  # for itself, so the default is a GPT-4.1 or Claude Sonnet class model, not a mini one, and
+  # :cursor drafts with any model on the user's Cursor account (see CursorLLM).
+  class LLM
+    OPENAI_BASE = "https://api.openai.com/v1"
+    ANTHROPIC_BASE = "https://api.anthropic.com/v1"
+
+    Reply = Struct.new(:text, :input_tokens, :output_tokens, keyword_init: true)
+
+    attr_reader :config
+
+    def initialize(config = PlanDriven.configuration, client: nil)
+      @config = config
+      @client = client
+    end
+
+    def chat(system:, messages:, max_tokens: 8000)
+      return wrap(@client.call(system: system, messages: messages)) if @client
+
+      case config.llm_provider.to_sym
+      when :cursor then CursorLLM.new(config).chat(system: system, messages: messages)
+      when :anthropic then anthropic(system, messages, max_tokens)
+      else openai(system, messages, max_tokens)
+      end
+    end
+
+    def label
+      "#{config.llm_provider}/#{config.llm_model}"
+    end
+
+    private
+
+    def anthropic?
+      config.llm_provider.to_sym == :anthropic
+    end
+
+    def api_key!
+      config.llm_api_key or
+        raise ConfigurationError, "No API key for #{config.llm_provider}. Run `plan-driven configure` or set " \
+                                  "#{anthropic? ? "ANTHROPIC_API_KEY" : "OPENAI_API_KEY"}."
+    end
+
+    def openai(system, messages, max_tokens)
+      body = { model: config.llm_model, temperature: config.temperature, max_completion_tokens: max_tokens,
+               response_format: { type: "json_object" },
+               messages: [{ role: "system", content: system }] + messages }
+      response = post("#{config.llm_api_base || OPENAI_BASE}/chat/completions", body,
+                      "Authorization" => "Bearer #{api_key!}")
+      usage = response["usage"] || {}
+      Reply.new(text: response.dig("choices", 0, "message", "content").to_s,
+                input_tokens: usage["prompt_tokens"], output_tokens: usage["completion_tokens"])
+    end
+
+    def anthropic(system, messages, max_tokens)
+      body = { model: config.llm_model, system: system, max_tokens: max_tokens, temperature: config.temperature,
+               messages: messages }
+      response = post("#{config.llm_api_base || ANTHROPIC_BASE}/messages", body,
+                      "x-api-key" => api_key!, "anthropic-version" => "2023-06-01")
+      usage = response["usage"] || {}
+      Reply.new(text: Array(response["content"]).filter_map { |part| part["text"] }.join,
+                input_tokens: usage["input_tokens"], output_tokens: usage["output_tokens"])
+    end
+
+    def post(url, body, headers)
+      response = HTTP.request(:post, url, headers: headers.merge("Content-Type" => "application/json"),
+                                          body: body, timeout: config.request_timeout)
+      return response.json if response.success?
+
+      message = response.json.dig("error", "message") || response.body.to_s[0, 200]
+      raise ProviderError, "#{config.llm_provider} returned #{response.status}: #{message}"
+    end
+
+    def wrap(value)
+      value.is_a?(Reply) ? value : Reply.new(text: value.to_s)
+    end
+  end
+end

data/lib/plan_driven/models/approval.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Approval < Record
+    DECISIONS = %w[approved rejected].freeze
+
+    belongs_to :approvable, polymorphic: true
+
+    validates :role, :actor, presence: true
+    validates :decision, inclusion: { in: DECISIONS }
+  end
+end

data/lib/plan_driven/models/event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # An append-only audit trail: who did what to which plan or ticket, and when.
+  class Event < Record
+    belongs_to :plan, class_name: "PlanDriven::Plan", inverse_of: :events
+    belongs_to :ticket, class_name: "PlanDriven::Ticket", optional: true
+
+    validates :name, :actor, presence: true
+
+    before_update { raise ActiveRecord::ReadOnlyRecord, "events are append-only" }
+  end
+end

data/lib/plan_driven/models/evidence_run.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class EvidenceRun < Record
+    belongs_to :plan, class_name: "PlanDriven::Plan", inverse_of: :evidence_runs
+
+    validates :kind, :status, presence: true
+
+    def scenarios
+      Array((results || {})["scenarios"])
+    end
+
+    def passed?
+      status == "passed"
+    end
+  end
+end

data/lib/plan_driven/models/plan.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Plan < Record
+    has_many :tickets, -> { order(:position) }, class_name: "PlanDriven::Ticket", dependent: :destroy,
+                                                inverse_of: :plan
+    has_many :approvals, as: :approvable, class_name: "PlanDriven::Approval", dependent: :destroy
+    has_many :events, -> { order(:created_at, :id) }, class_name: "PlanDriven::Event", dependent: :destroy,
+                                                      inverse_of: :plan
+    has_many :evidence_runs, -> { order(:created_at) }, class_name: "PlanDriven::EvidenceRun",
+                                                        dependent: :destroy, inverse_of: :plan
+
+    validates :key, :title, presence: true
+    validates :key, uniqueness: true
+    validates :status, inclusion: { in: Workflow::PLAN.keys }
+
+    before_validation :assign_key, on: :create
+
+    def self.find_by_reference!(reference)
+      reference = reference.to_s
+      find_by(key: reference.upcase) || find_by(id: reference[/\A\d+\z/]) ||
+        raise(ActiveRecord::RecordNotFound, "No plan #{reference}. `plan-driven list` shows them all.")
+    end
+
+    def section(key)
+      (sections || {})[key.to_s].to_s
+    end
+
+    EDITABLE = %w[draft in_review approved].freeze
+
+    def editable?
+      EDITABLE.include?(status)
+    end
+
+    # Any edit is a new revision, and approvals belong to a revision, so changing an approved
+    # plan sends it back for approval.
+    def update_sections!(changes, actor:)
+      unless editable?
+        raise TransitionError, "plan #{key} is #{status}; its tickets are drafted, so the plan can't change. " \
+                               "Start a follow-up plan instead."
+      end
+
+      merged = (sections || {}).merge(changes.transform_keys(&:to_s))
+      transaction do
+        update!(sections: merged, revision: revision + 1)
+        log!("plan.revised", actor: actor, sections: changes.keys.map(&:to_s))
+        Workflow.plan_transition!(self, "draft") unless status == "draft"
+      end
+    end
+
+    def slug
+      "#{key.downcase}-#{title.parameterize[0, 60]}".delete_suffix("-")
+    end
+
+    def approvals_for_revision
+      approvals.where(revision: revision)
+    end
+
+    def approved_roles
+      approvals_for_revision.where(decision: "approved").pluck(:role).uniq
+    end
+
+    def missing_approvals(required = PlanDriven.configuration.plan_approvals)
+      required.map(&:to_s) - approved_roles
+    end
+
+    def ticket_approved_roles
+      approvals.where(role: ticket_roles.map { |role| "tickets:#{role}" }, decision: "approved",
+                      revision: revision).pluck(:role).map { |role| role.delete_prefix("tickets:") }.uniq
+    end
+
+    def missing_ticket_approvals
+      ticket_roles - ticket_approved_roles
+    end
+
+    def log!(name, actor:, ticket: nil, **payload)
+      events.create!(name: name, actor: actor, ticket: ticket, payload: payload.presence)
+    end
+
+    def ticket!(reference)
+      tickets.find_by(key: reference.to_s.upcase) ||
+        raise(ActiveRecord::RecordNotFound, "Plan #{key} has no ticket #{reference}.")
+    end
+
+    private
+
+    def ticket_roles
+      PlanDriven.configuration.ticket_approvals.map(&:to_s)
+    end
+
+    def assign_key
+      return if key.present?
+
+      last = self.class.where("key LIKE 'PD-%'").pluck(:key).map { |value| value.delete_prefix("PD-").to_i }.max
+      self.key = "PD-#{last.to_i + 1}"
+    end
+  end
+end

data/lib/plan_driven/models/record.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Record < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name_prefix = "plan_driven_"
+  end
+end

data/lib/plan_driven/models/ticket.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Ticket < Record
+    KINDS = %w[migration dual_write backfill code switch cleanup docs].freeze
+    TYPES = %w[TASK STORY BUG].freeze
+
+    belongs_to :plan, class_name: "PlanDriven::Plan", inverse_of: :tickets
+    has_many :approvals, as: :approvable, class_name: "PlanDriven::Approval", dependent: :destroy
+
+    validates :key, :title, presence: true
+    validates :kind, inclusion: { in: KINDS }
+    validates :ticket_type, inclusion: { in: TYPES }
+    validates :status, inclusion: { in: Workflow::TICKET.keys }
+
+    def reference
+      "#{plan.key}/#{key}"
+    end
+
+    def criteria
+      Array(acceptance_criteria)
+    end
+
+    def dependencies
+      Array(depends_on)
+    end
+
+    def tables
+      Array(touches)
+    end
+
+    def dependency_tickets
+      plan.tickets.select { |ticket| dependencies.include?(ticket.key) }
+    end
+
+    # Ready to hand to an agent: approved and everything it builds on is merged, so the agent
+    # starts from a branch that already contains it.
+    def ready?
+      status == "approved" && dependency_tickets.all? { |ticket| ticket.status == "merged" }
+    end
+
+    def blocked_by
+      dependency_tickets.reject { |ticket| ticket.status == "merged" }.map(&:key)
+    end
+
+    def active_agent?
+      status == "running"
+    end
+
+    def feature_tag
+      "@#{plan.key.downcase}-#{key.downcase}"
+    end
+
+    def pr_approved_by
+      approvals.where(role: "pr", decision: "approved").order(:created_at).last&.actor
+    end
+  end
+end

data/lib/plan_driven/models.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "models/record"
+require_relative "models/plan"
+require_relative "models/ticket"
+require_relative "models/approval"
+require_relative "models/event"
+require_relative "models/evidence_run"

data/lib/plan_driven/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Railtie < Rails::Railtie
+    generators do
+      require_relative "../generators/plan_driven/install_generator"
+    end
+  end
+end

data/lib/plan_driven/renderer/html.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Renderer
+    # A small Markdown-to-HTML converter for the documents this gem writes: headings, paragraphs,
+    # lists, tables, code blocks, emphasis and links. It isn't a general Markdown implementation,
+    # and doesn't need to be.
+    module HTML
+      STYLE = File.read(File.expand_path("style.css", __dir__))
+
+      module_function
+
+      def document(markdown, title:)
+        <<~HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+          <meta charset="utf-8">
+          <title>#{CGI.escapeHTML(title)}</title>
+          <style>#{STYLE}</style>
+          </head>
+          <body>
+          <main>
+          #{convert(markdown)}
+          </main>
+          </body>
+          </html>
+        HTML
+      end
+
+      def convert(markdown)
+        lines = markdown.to_s.lines.map(&:chomp)
+        out = []
+        until lines.empty?
+          line = lines.first
+          if line.start_with?("```")
+            out << code_block(lines)
+          elsif line.match?(/\A\s*\|/)
+            out << table(take_while(lines) { |l| l.match?(/\A\s*\|/) })
+          elsif (match = line.match(/\A(\#{1,6})\s+(.*)\z/))
+            lines.shift
+            level = match[1].size
+            out << "<h#{level}>#{inline(match[2])}</h#{level}>"
+          elsif line.match?(/\A\s*([-*]|\d+\.)\s+/)
+            out << list(take_while(lines) { |l| l.match?(/\A\s*([-*]|\d+\.)\s+/) || l.match?(/\A\s{2,}\S/) })
+          elsif line.strip.empty?
+            lines.shift
+          else
+            paragraph = take_while(lines) { |l| !l.strip.empty? && !l.match?(/\A(#|```|\s*\||\s*([-*]|\d+\.)\s)/) }
+            paragraph = [lines.shift] if paragraph.empty?
+            out << "<p>#{inline(paragraph.join(" "))}</p>"
+          end
+        end
+        out.join("\n")
+      end
+
+      def take_while(lines)
+        taken = []
+        taken << lines.shift while lines.any? && yield(lines.first)
+        taken
+      end
+
+      def code_block(lines)
+        lines.shift
+        body = take_while(lines) { |line| !line.start_with?("```") }
+        lines.shift
+        "<pre><code>#{CGI.escapeHTML(body.join("\n"))}</code></pre>"
+      end
+
+      def table(rows)
+        cells = rows.map { |row| row.strip.delete_prefix("|").delete_suffix("|").split(/(?<!\\)\|/).map(&:strip) }
+        header, *body = cells
+        body = body.reject { |row| row.all? { |cell| cell.match?(/\A:?-+:?\z/) } }
+        head = header.map { |cell| "<th>#{inline(cell)}</th>" }.join
+        rows = body.map { |row| "<tr>#{row.map { |cell| "<td>#{inline(cell.gsub("\\|", "|"))}</td>" }.join}</tr>" }
+        "<table><thead><tr>#{head}</tr></thead><tbody>#{rows.join}</tbody></table>"
+      end
+
+      def list(lines)
+        ordered = lines.first.match?(/\A\s*\d+\./)
+        items = []
+        lines.each do |line|
+          if line.match?(/\A\s*([-*]|\d+\.)\s+/)
+            items << line.sub(/\A\s*([-*]|\d+\.)\s+/, "")
+          else
+            items[-1] = "#{items.last} #{line.strip}"
+          end
+        end
+        tag = ordered ? "ol" : "ul"
+        "<#{tag}>#{items.map { |item| "<li>#{inline(item)}</li>" }.join}</#{tag}>"
+      end
+
+      def inline(text)
+        codes = []
+        escaped = CGI.escapeHTML(text.to_s).gsub(/`([^`]+)`/) do
+          codes << Regexp.last_match(1)
+          "\u0000#{codes.size - 1}\u0000"
+        end
+        escaped = escaped.gsub(/\*\*(.+?)\*\*/, '<strong>\1</strong>')
+                         .gsub(/(?<![*\w])\*(?!\s)(.+?)(?<!\s)\*(?![*\w])/, '<em>\1</em>')
+                         .gsub(/\[([^\]]+)\]\((https?:[^)\s]+|[^)\s]+\.(?:md|html|pdf))\)/, '<a href="\2">\1</a>')
+        escaped.gsub(/\u0000(\d+)\u0000/) { "<code>#{codes[Regexp.last_match(1).to_i]}</code>" }
+      end
+    end
+  end
+end