plan_driven 0.1.0

data/lib/plan_driven/renderer/markdown.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Renderer
+    # The plan and the delivery report as Markdown, laid out like a Confluence implementation plan.
+    module Markdown
+      module_function
+
+      def plan(plan, config: PlanDriven.configuration)
+        parts = ["# #{plan.key}: #{plan.title}", meta(plan)]
+        config.template.grouped.each do |group, sections|
+          body = sections.filter_map { |section| section_block(plan, section, group) }
+          body << tickets_table(plan) if group == "Work overview" && plan.tickets.any?
+          parts << "# #{group}\n\n#{body.join("\n\n")}" if body.any?
+        end
+        parts << approvals_table(plan, config)
+        "#{parts.join("\n\n")}\n"
+      end
+
+      def report(plan)
+        parts = ["# #{plan.key}: #{plan.title} (delivery report)", meta(plan)]
+        parts << "## Summary\n\n#{summary(plan)}"
+        parts << "## Tickets and pull requests\n\n#{delivery_table(plan)}"
+        parts << "## Acceptance criteria and proof\n\n#{Evidence.matrix_markdown(plan)}"
+        parts << "## Checks run on each pull request\n\n#{guard_findings(plan)}"
+        parts << "## Approvals\n\n#{approval_history(plan)}"
+        parts << "## Timeline\n\n#{timeline(plan)}"
+        parts << "## The approved plan\n\nThe plan this delivery implements is in `plan.md`, revision #{plan.revision}."
+        "#{parts.join("\n\n")}\n"
+      end
+
+      def section_block(plan, section, group)
+        text = plan.section(section.key).strip
+        return if text.empty?
+
+        heading = section.title == group ? "" : "## #{section.title}\n\n"
+        "#{heading}#{text}"
+      end
+
+      def meta(plan)
+        "*Status: #{plan.status.tr("_", " ")} · Revision #{plan.revision} · Created by #{plan.created_by} · " \
+          "#{plan.created_at&.strftime("%-d %B %Y")}*"
+      end
+
+      def tickets_table(plan)
+        rows = plan.tickets.map do |ticket|
+          [ticket.key, ticket.title, ticket.ticket_type, ticket.kind, ticket.estimate,
+           ticket.dependencies.join(", ").presence || "-", issue_link(ticket)]
+        end
+        details = plan.tickets.map { |ticket| ticket_detail(ticket) }
+        "## Work items\n\n#{table(%w[# Title Type Kind Estimate Depends Issue], rows)}\n\n" \
+          "**Estimated total: #{plan.tickets.sum { |ticket| ticket.estimate.to_i }} points**\n\n#{details.join("\n\n")}"
+      end
+
+      def ticket_detail(ticket)
+        lines = ["### #{ticket.key}. #{ticket.title}"]
+        lines << ticket.story if ticket.story.present?
+        lines << ticket.description.to_s
+        lines << "#### Acceptance Criteria\n\n#{ticket.criteria.each_with_index.map do |c, i|
+          "#{i + 1}. #{c}"
+        end.join("\n")}"
+        lines << "#### Implementation Notes\n\n#{ticket.implementation_notes}" if ticket.implementation_notes.present?
+        lines << "*Touches: #{ticket.tables.join(", ")}*" if ticket.tables.any?
+        lines.join("\n\n")
+      end
+
+      def approvals_table(plan, config)
+        roles = config.plan_approvals
+        rows = roles.map do |role|
+          approval = plan.approvals_for_revision.where(role: role).order(:created_at).last
+          [role.tr("_", " ").capitalize, approval&.decision || "pending", approval&.actor || "",
+           approval&.created_at&.strftime("%-d %b %Y %H:%M") || ""]
+        end
+        "# Sign-off\n\n#{table(%w[Role Decision By When], rows)}"
+      end
+
+      def summary(plan)
+        tickets = plan.tickets
+        merged = tickets.count { |ticket| ticket.status == "merged" }
+        "#{merged} of #{tickets.size} tickets merged. #{Evidence.summary_line(plan)}"
+      end
+
+      def delivery_table(plan)
+        rows = plan.tickets.map do |ticket|
+          [ticket.key, ticket.title, ticket.status.tr("_", " "), pr_link(ticket),
+           ticket.merged_sha.to_s[0, 7].presence || "-", ticket.pr_approved_by || "-"]
+        end
+        table(["#", "Ticket", "Status", "Pull request", "Merge commit", "Approved by"], rows)
+      end
+
+      def guard_findings(plan)
+        lines = plan.tickets.map do |ticket|
+          report = Guards::Report.from_h(ticket.guard_report)
+          if ticket.guard_report.nil?
+            "- **#{ticket.key}**: not reviewed"
+          elsif report.errors.empty? && report.warnings.empty?
+            "- **#{ticket.key}**: all checks passed"
+          else
+            items = report.errors.map { |e| "error: #{e}" } + report.warnings.map { |w| "warning: #{w}" }
+            "- **#{ticket.key}**: #{items.join("; ")}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def approval_history(plan)
+        approvals = Approval.where(approvable: [plan, *plan.tickets]).order(:created_at)
+        return "No approvals recorded." if approvals.empty?
+
+        rows = approvals.map do |approval|
+          approvable = approval.approvable
+          subject = approvable.is_a?(Ticket) ? "#{approvable.key} pull request" : "plan r#{approval.revision}"
+          [approval.created_at.strftime("%-d %b %Y %H:%M"), subject, approval.role, approval.decision, approval.actor,
+           approval.note.to_s]
+        end
+        table(%w[When Subject Role Decision By Note], rows)
+      end
+
+      def timeline(plan)
+        plan.events.map do |event|
+          target = event.ticket ? " #{event.ticket.key}" : ""
+          "- #{event.created_at.strftime("%-d %b %Y %H:%M")} · #{event.name}#{target} · #{event.actor}"
+        end.join("\n")
+      end
+
+      def issue_link(ticket)
+        return "-" unless ticket.issue_number
+
+        slug = Repository.slug
+        number = ticket.issue_number
+        slug ? "[##{number}](https://github.com/#{slug}/issues/#{number})" : "##{number}"
+      end
+
+      def pr_link(ticket)
+        ticket.pr_url ? "[##{ticket.pr_number}](#{ticket.pr_url})" : "-"
+      end
+
+      def table(headers, rows)
+        escape = ->(value) { value.to_s.gsub("|", "\\|").gsub("\n", " ") }
+        lines = ["| #{headers.join(" | ")} |", "| #{headers.map { "---" }.join(" | ")} |"]
+        (lines + rows.map { |row| "| #{row.map(&escape).join(" | ")} |" }).join("\n")
+      end
+    end
+  end
+end

data/lib/plan_driven/renderer/pdf.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  module Renderer
+    # Prints the HTML to PDF with headless Chrome or Chromium, when one is installed. A custom
+    # `config.pdf_renderer` (any callable taking the HTML and PDF paths) replaces it.
+    module PDF
+      BROWSERS = [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "google-chrome", "google-chrome-stable", "chromium", "chromium-browser"
+      ].freeze
+
+      module_function
+
+      def render(html_path, pdf_path, config: PlanDriven.configuration)
+        return config.pdf_renderer.call(html_path.to_s, pdf_path.to_s) && File.exist?(pdf_path) if config.pdf_renderer
+
+        browser = self.browser
+        return false unless browser
+
+        system(browser, "--headless", "--disable-gpu", "--no-pdf-header-footer", "--no-sandbox",
+               "--print-to-pdf=#{pdf_path}", "file://#{File.expand_path(html_path)}",
+               out: File::NULL, err: File::NULL)
+        File.exist?(pdf_path)
+      end
+
+      def browser
+        BROWSERS.find do |candidate|
+          candidate.start_with?("/") ? File.executable?(candidate) : executable_on_path?(candidate)
+        end
+      end
+
+      def executable_on_path?(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+      end
+    end
+  end
+end

data/lib/plan_driven/renderer/style.css

@@ -0,0 +1,22 @@
+@page { size: A4; margin: 18mm 16mm; }
+* { box-sizing: border-box; }
+body { font: 10.5pt/1.55 -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; color: #1f2328; margin: 0; }
+main { max-width: 880px; margin: 0 auto; padding: 24px; }
+h1 { font-size: 21pt; margin: 28px 0 8px; padding-bottom: 6px; border-bottom: 2px solid #d0d7de; }
+h1:first-child { margin-top: 0; font-size: 24pt; border-bottom: 0; }
+h2 { font-size: 14.5pt; margin: 22px 0 6px; }
+h3 { font-size: 12pt; margin: 18px 0 4px; }
+h4 { font-size: 10.5pt; margin: 14px 0 4px; text-transform: uppercase; letter-spacing: .04em; color: #57606a; }
+p { margin: 6px 0 10px; }
+ul, ol { margin: 6px 0 10px; padding-left: 22px; }
+li { margin: 2px 0; }
+em { color: #57606a; }
+code { font: 9pt/1.4 "SFMono-Regular", Menlo, Consolas, monospace; background: #f6f8fa; padding: 1px 4px; border-radius: 4px; }
+pre { background: #f6f8fa; border: 1px solid #d0d7de; border-radius: 6px; padding: 10px 12px; overflow-x: auto; }
+pre code { background: none; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 8px 0 14px; font-size: 9.5pt; break-inside: auto; }
+th, td { border: 1px solid #d0d7de; padding: 5px 8px; text-align: left; vertical-align: top; }
+th { background: #f6f8fa; font-weight: 600; }
+tr { break-inside: avoid; }
+a { color: #0969da; text-decoration: none; }
+h1, h2, h3 { break-after: avoid; }

data/lib/plan_driven/renderer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "fileutils"
+
+require_relative "renderer/markdown"
+require_relative "renderer/html"
+require_relative "renderer/pdf"
+
+module PlanDriven
+  # Writes a plan's documentation under docs/plans/<plan-slug>/: the plan and the delivery report,
+  # each as Markdown (for the repository), HTML and PDF (for people who don't read Markdown).
+  module Renderer
+    module_function
+
+    def write_plan(plan, config: PlanDriven.configuration)
+      write(plan, "plan", Markdown.plan(plan, config: config), title: "#{plan.key} #{plan.title}", config: config)
+    end
+
+    def write_report(plan, config: PlanDriven.configuration)
+      write(plan, "delivery-report", Markdown.report(plan),
+            title: "#{plan.key} delivery report", config: config)
+    end
+
+    def directory(plan, config: PlanDriven.configuration)
+      config.docs_root.join(plan.slug)
+    end
+
+    def write(plan, name, markdown, title:, config:)
+      dir = directory(plan, config: config)
+      FileUtils.mkdir_p(dir)
+      md = dir.join("#{name}.md")
+      html = dir.join("#{name}.html")
+      pdf = dir.join("#{name}.pdf")
+      File.write(md, markdown)
+      File.write(html, HTML.document(markdown, title: title))
+      written = PDF.render(html, pdf, config: config)
+      { markdown: md, html: html, pdf: written ? pdf : nil }
+    end
+  end
+end

data/lib/plan_driven/repository.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module PlanDriven
+  # The GitHub repository the application lives in, from config or the `origin` remote.
+  module Repository
+    # Also matches SSH host aliases such as git@github.com-work:acme/app.git.
+    REMOTE = %r{github\.com(?:-[\w.-]+)?[:/]([\w.-]+/[\w.-]+?)(?:\.git)?/?\z}
+
+    module_function
+
+    def slug(config = PlanDriven.configuration)
+      config.github_repository.presence || from_remote(config.root_path)
+    end
+
+    def from_remote(root)
+      output, status = Open3.capture2("git", "-C", root.to_s, "remote", "get-url", "origin", err: File::NULL)
+      return unless status.success?
+
+      parse(output.strip)
+    rescue StandardError
+      nil
+    end
+
+    def parse(url)
+      url.to_s.strip[REMOTE, 1]
+    end
+
+    def head_sha(root = PlanDriven.configuration.root_path)
+      output, status = Open3.capture2("git", "-C", root.to_s, "rev-parse", "HEAD", err: File::NULL)
+      status.success? ? output.strip : nil
+    end
+  end
+end

data/lib/plan_driven/schema_context.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # What the application looks like, read from the database connection and ActiveRecord models.
+  # The model is told this so a plan describes the real schema, and the guards use it to catch a
+  # plan that describes tables or columns that don't exist.
+  class SchemaContext
+    IGNORED_TABLES = /\A(schema_migrations|ar_internal_metadata|plan_driven_|active_storage_|action_text_|
+                     action_mailbox_|solid_(queue|cache|cable)_)/x
+
+    Model = Struct.new(:name, :table, :path, :associations, keyword_init: true)
+
+    def initialize(connection: ActiveRecord::Base.connection, root: PlanDriven.configuration.root_path)
+      @connection = connection
+      @root = Pathname(root)
+    end
+
+    def adapter
+      @connection.adapter_name
+    end
+
+    def tables
+      @tables ||= @connection.tables.grep_v(IGNORED_TABLES).sort
+    end
+
+    def columns(table)
+      @columns ||= {}
+      @columns[table.to_s] ||= @connection.columns(table.to_s).map do |column|
+        [column.name, column.sql_type_metadata.type.to_s, column.null ? nil : "not null"].compact
+      end
+    end
+
+    def column?(table, column)
+      tables.include?(table.to_s) && columns(table).any? { |name, *| name == column.to_s }
+    end
+
+    def table?(table)
+      tables.include?(table.to_s)
+    end
+
+    def models
+      @models ||= load_models
+    end
+
+    def model_names
+      models.map(&:name)
+    end
+
+    def model?(name)
+      model_names.include?(name.to_s)
+    end
+
+    def to_prompt
+      return "The application has no tables yet." if tables.empty?
+
+      by_table = models.group_by(&:table)
+      tables.map { |table| describe(table, by_table[table]) }.join("\n\n")
+    end
+
+    private
+
+    def describe(table, table_models)
+      header = if table_models&.any?
+                 "#{table_models.map { |model| "#{model.name} (#{model.path || "no file"})" }.join(", ")} -> #{table}"
+               else
+                 "#{table} (no model)"
+               end
+      lines = [header, "  columns: #{columns(table).map { |parts| parts.join(":") }.join(", ")}"]
+      Array(table_models).flat_map(&:associations).uniq.each { |association| lines << "  #{association}" }
+      lines.join("\n")
+    end
+
+    def load_models
+      Rails.application.eager_load! if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+      ActiveRecord::Base.descendants.filter_map do |klass|
+        next if klass.abstract_class? || klass.name.nil? || klass.name.start_with?("PlanDriven::")
+        next unless table?(klass.table_name)
+
+        Model.new(name: klass.name, table: klass.table_name, path: model_path(klass),
+                  associations: klass.reflect_on_all_associations.map { |reflection| association_line(reflection) })
+      rescue StandardError
+        nil
+      end.sort_by(&:name)
+    end
+
+    def association_line(reflection)
+      line = "#{reflection.macro} :#{reflection.name}"
+      line += " through: :#{reflection.options[:through]}" if reflection.options[:through]
+      line += " polymorphic" if reflection.options[:polymorphic]
+      line
+    end
+
+    def model_path(klass)
+      relative = "app/models/#{klass.name.underscore}.rb"
+      @root.join(relative).exist? ? relative : nil
+    end
+  end
+end

data/lib/plan_driven/template.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # The shape of an implementation plan. The default follows the structure Rails teams already
+  # write in Confluence: Overview, Background, Architectural changes, Work overview, Risks,
+  # Testing and sign-off. Sections marked `ask` come from the person in the terminal; the rest
+  # are drafted by the model from the answers and the real schema, then checked by the guards.
+  class Template
+    Section = Struct.new(:key, :title, :group, :source, :required, :question, :guidance, :min_words,
+                         keyword_init: true) do
+      def asked?
+        source == :ask
+      end
+
+      def drafted?
+        source == :draft
+      end
+    end
+
+    GROUPS = ["Overview", "Background", "Architectural changes", "Work overview", "Risks", "Testing"].freeze
+
+    attr_reader :sections
+
+    def self.default
+      new(DEFAULT_SECTIONS)
+    end
+
+    def initialize(sections)
+      @sections = sections.map { |section| section.is_a?(Section) ? section : Section.new(**section) }
+    end
+
+    def [](key)
+      sections.find { |section| section.key == key.to_s }
+    end
+
+    def keys
+      sections.map(&:key)
+    end
+
+    def asked
+      sections.select(&:asked?)
+    end
+
+    def drafted
+      sections.select(&:drafted?)
+    end
+
+    def required
+      sections.select(&:required)
+    end
+
+    def grouped
+      GROUPS.to_h { |group| [group, sections.select { |section| section.group == group }] }
+    end
+
+    DEFAULT_SECTIONS = [
+      { key: "what", title: "What", group: "Overview", source: :ask, required: true, min_words: 15,
+        question: "What are we building? Describe the change as the user will see it.",
+        guidance: "The change in two or three short paragraphs, in product terms." },
+      { key: "why", title: "Why", group: "Overview", source: :ask, required: true, min_words: 10,
+        question: "Why now? What problem or gap does it close?",
+        guidance: "The problem, the gap or the business reason, as a short list if there are several." },
+      { key: "where", title: "Where", group: "Overview", source: :ask, required: true, min_words: 2,
+        question: "Where in the product does it land? (modules, screens, APIs)",
+        guidance: "The modules, screens, APIs and jobs affected." },
+      { key: "who", title: "Who", group: "Overview", source: :ask, required: true, min_words: 1,
+        question: "Who owns it? (team, people)", guidance: "Owning team and people." },
+      { key: "when", title: "When", group: "Overview", source: :ask, required: false, min_words: 0,
+        question: "When is it needed? (date, milestone, or leave empty)", guidance: "Target date or milestone." },
+      { key: "background", title: "Background", group: "Background", source: :ask, required: false, min_words: 0,
+        question: "Links, PRDs, existing tickets, earlier decisions (optional)",
+        guidance: "Links, product documents, related tickets and earlier decisions." },
+      { key: "existing_data_structure", title: "Existing Data Structure", group: "Background", source: :draft,
+        required: true, min_words: 30,
+        guidance: "The existing models, tables, columns and associations this change touches, one subsection " \
+                  "per model with its file path (for example `app/models/form.rb`). Only describe what exists " \
+                  "in the schema you were given." },
+      { key: "architecture", title: "Architectural changes", group: "Architectural changes", source: :draft,
+        required: true, min_words: 40,
+        guidance: "The target design and data flow. Keep the existing execution shape where possible. Explain " \
+                  "how legacy data coexists with the new model during rollout." },
+      { key: "database_changes", title: "Database changes", group: "Architectural changes", source: :draft,
+        required: true, min_words: 20,
+        guidance: "Every table and column added, changed or removed, with type, nullability, default and " \
+                  "indexes. Changes must be additive first (expand, dual write, backfill, switch reads, " \
+                  "then contract). Removing or renaming a column needs `ignored_columns` in an earlier step." },
+      { key: "application_changes", title: "Application changes", group: "Architectural changes", source: :draft,
+        required: true, min_words: 40,
+        guidance: "Models, services, controllers, policies, jobs and UI that change, one subsection each." },
+      { key: "infrastructure_changes", title: "Infrastructure changes", group: "Architectural changes",
+        source: :draft, required: true, min_words: 5,
+        guidance: "Queues, external services, feature flags and rollout order. Say so when there are none." },
+      { key: "out_of_scope", title: "Out of Scope", group: "Work overview", source: :ask, required: false,
+        min_words: 0, question: "What is explicitly out of scope? (optional)",
+        guidance: "What this plan deliberately doesn't do." },
+      { key: "risks", title: "Risks", group: "Risks", source: :draft, required: true, min_words: 15,
+        guidance: "The main risks as a list, and how each is mitigated." },
+      { key: "performance", title: "Performance", group: "Risks", source: :draft, required: true, min_words: 10,
+        guidance: "Query counts, N+1 risks, indexes, large tables, batch sizes for backfills." },
+      { key: "security", title: "Security", group: "Risks", source: :draft, required: true, min_words: 10,
+        guidance: "Authorization, data exposure and input validation. End with a line `Risk Level: LOW`, " \
+                  "`MEDIUM` or `HIGH` and one sentence why." },
+      { key: "monitoring", title: "Monitoring", group: "Risks", source: :draft, required: false, min_words: 0,
+        guidance: "What to watch after release: errors, jobs, metrics." },
+      { key: "outstanding_questions", title: "Outstanding questions", group: "Risks", source: :draft,
+        required: false, min_words: 0,
+        guidance: "Open questions that must be answered before a phase ships. Don't invent answers." },
+      { key: "testing", title: "Testing", group: "Testing", source: :draft, required: true, min_words: 20,
+        guidance: "Model, service, policy, request and system coverage, as a list of the main cases, " \
+                  "including legacy data and permissions." }
+    ].freeze
+  end
+end

data/lib/plan_driven/ticket_generator.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Splits an approved plan into tickets. Deterministic fixes come first, then the guard; errors
+  # go back to the model as a list, the same way plans are repaired.
+  class TicketGenerator
+    Result = Struct.new(:tickets, :report, :attempts, keyword_init: true)
+
+    FIELDS = <<~TEXT.freeze
+      key: "T1", "T2", ... in delivery order
+      title: short, imperative ("Migration: Add formable columns to forms")
+      kind: one of #{Ticket::KINDS.join(", ")}
+      type: TASK, STORY or BUG
+      story: "I want ..., so that ..." (required for STORY)
+      description: what to build, precise enough for a developer who hasn't read the plan
+      acceptance_criteria: array of testable statements, each one becomes a Cucumber scenario
+      implementation_notes: file paths, column mappings, code hints (optional)
+      estimate: story points
+      depends_on: keys of tickets that must be merged first
+      touches: table names this ticket changes or reads in a new way
+    TEXT
+
+    def initialize(llm: LLM.new, schema: SchemaContext.new, config: PlanDriven.configuration)
+      @llm = llm
+      @schema = schema
+      @config = config
+    end
+
+    def generate(plan, instruction: nil)
+      content = request(plan)
+      content += "\n\nThe reviewer asks for this breakdown: #{instruction}" if instruction.present?
+      messages = [{ role: "user", content: content }]
+      attempts = 0
+
+      loop do
+        attempts += 1
+        reply = @llm.chat(system: system_prompt, messages: messages)
+        begin
+          drafted = parse(reply.text)
+        rescue InvalidResponseError => e
+          raise if attempts > @config.max_repair_attempts
+
+          messages += [{ role: "assistant", content: reply.text },
+                       { role: "user",
+                         content: "That reply can't be used: #{e.message}. Reply with the JSON object only." }]
+          next
+        end
+        report = Guards::Report.new
+        tickets = Guards::TicketNormalizer.new(drafted, config: @config).call(report)
+        report.merge!(Guards::TicketGuard.new(tickets, plan_sections: plan.sections, schema: @schema,
+                                                       config: @config).call)
+        if report.ok? || attempts > @config.max_repair_attempts
+          return Result.new(tickets: tickets, report: report, attempts: attempts)
+        end
+
+        messages += [{ role: "assistant", content: reply.text }, { role: "user", content: repair(report) }]
+      end
+    end
+
+    def system_prompt
+      <<~PROMPT
+        You split an approved Rails implementation plan into tickets. Each ticket becomes one
+        pull request written by a coding agent and reviewed by a human, so each must merge on
+        its own without breaking the application.
+
+        Order the work the way zero-downtime Rails changes ship: migrations that add, dual
+        writes, backfills, switching reads, then cleanup that removes. A ticket may only depend
+        on tickets before it. Keep tickets small: at most #{@config.max_estimate} points on the
+        scale #{@config.estimate_scale.join(", ")}. Schema changes get their own migration tickets.
+        Split code by behaviour, not by layer: each code ticket delivers one thing a user can do,
+        with its model, service, controller, view and specs together, so its acceptance criteria
+        can be proven by Cucumber scenarios.
+
+        Reply with one JSON object: {"tickets": [ ... ]}. Each ticket has:
+        #{FIELDS}
+      PROMPT
+    end
+
+    private
+
+    def request(plan)
+      sections = plan.sections.map { |key, value| "## #{@config.template[key]&.title || key}\n#{value}" }
+      "Plan #{plan.key}: #{plan.title}\n\n#{sections.join("\n\n")}"
+    end
+
+    def repair(report)
+      "These problems must be fixed:\n#{report.errors.map { |error| "- #{error}" }.join("\n")}\n\n" \
+        "Reply with the full JSON again, every ticket included."
+    end
+
+    def parse(text)
+      tickets = JsonReply.parse(text)["tickets"]
+      raise InvalidResponseError, "the reply had no \"tickets\" array" unless tickets.is_a?(Array)
+
+      tickets
+    end
+  end
+end

data/lib/plan_driven/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  VERSION = "0.1.0"
+end

data/lib/plan_driven/workflow.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # The phases a plan and its tickets move through. Transitions are data, so the CLI, the specs
+  # and the documentation all read the same table.
+  module Workflow
+    PLAN = {
+      "draft" => %w[in_review],
+      "in_review" => %w[draft approved],
+      "approved" => %w[draft ticketed],
+      "ticketed" => %w[approved tickets_approved],
+      "tickets_approved" => %w[in_development ticketed],
+      "in_development" => %w[delivered],
+      "delivered" => []
+    }.freeze
+
+    TICKET = {
+      "draft" => %w[approved],
+      "approved" => %w[running],
+      "running" => %w[pr_open failed],
+      "pr_open" => %w[changes_requested pr_approved merged],
+      "changes_requested" => %w[running],
+      "pr_approved" => %w[merged changes_requested],
+      "failed" => %w[running],
+      "merged" => []
+    }.freeze
+
+    PLAN_DESCRIPTIONS = {
+      "draft" => "being written; edit it, then `plan-driven submit`",
+      "in_review" => "waiting for approval: `plan-driven approve`",
+      "approved" => "approved; `plan-driven tickets` drafts the tickets",
+      "ticketed" => "tickets drafted; review them, then `plan-driven approve-tickets`",
+      "tickets_approved" => "ready; `plan-driven develop` hands tickets to agents",
+      "in_development" => "agents are working; `plan-driven status` and `plan-driven review`",
+      "delivered" => "every ticket merged; `plan-driven report` writes the delivery report"
+    }.freeze
+
+    module_function
+
+    def plan_transition!(plan, to)
+      transition!(PLAN, plan, to, "plan #{plan.key}")
+    end
+
+    def ticket_transition!(ticket, to)
+      transition!(TICKET, ticket, to, "ticket #{ticket.key}")
+    end
+
+    def transition!(table, record, to, label)
+      from = record.status
+      unless table.fetch(from, []).include?(to)
+        allowed = table.fetch(from, [])
+        hint = allowed.empty? ? "it's final" : "it can move to #{allowed.join(", ")}"
+        raise TransitionError, "#{label} is #{from}; it can't move to #{to} (#{hint})"
+      end
+
+      record.update!(status: to)
+    end
+  end
+end