plan_driven 0.1.0

data/lib/plan_driven/delivery.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # The whole process, one method per step. Each step checks the phase, runs its guard, records
+  # who did it, and leaves documentation behind. The CLI is a thin layer over this.
+  class Delivery
+    attr_reader :actor, :config
+
+    def initialize(actor: PlanDriven.actor, config: PlanDriven.configuration, llm: nil, schema: nil,
+                   github: nil, agents: nil)
+      @actor = actor
+      @config = config
+      @llm = llm
+      @schema = schema
+      @github = github
+      @agents = agents
+    end
+
+    # -- Plan -------------------------------------------------------------------------------------
+
+    def create_plan(title:, answers:)
+      result = drafter.draft(answers, title: title)
+      plan = Plan.create!(title: title, interview: answers, sections: result.sections, created_by: actor,
+                          guard_report: result.report.to_h)
+      plan.log!("plan.drafted", actor: actor, model: llm.label, attempts: result.attempts,
+                                assumptions: result.assumptions)
+      Renderer.write_plan(plan, config: config)
+      [plan, result]
+    end
+
+    def check_plan(plan)
+      report = Guards::PlanGuard.new(plan.sections, schema: schema, template: config.template).call
+      plan.update!(guard_report: report.to_h)
+      report
+    end
+
+    def edit_section(plan, key, text)
+      plan.update_sections!({ key => text }, actor: actor)
+      check_plan(plan)
+      Renderer.write_plan(plan, config: config)
+    end
+
+    def redraft_section(plan, key, instruction)
+      text = drafter.redraft(plan.sections, key, instruction)
+      edit_section(plan, key, text)
+      text
+    end
+
+    def submit(plan)
+      report = check_plan(plan)
+      raise GuardError, report.errors unless report.ok?
+
+      Workflow.plan_transition!(plan, "in_review")
+      plan.log!("plan.submitted", actor: actor, revision: plan.revision, warnings: report.warnings)
+      Renderer.write_plan(plan, config: config)
+    end
+
+    def approve_plan(plan, role:, note: nil)
+      decide(plan, role: role, decision: "approved", note: note)
+      if plan.missing_approvals.empty?
+        Workflow.plan_transition!(plan, "approved")
+        plan.log!("plan.approved", actor: actor, revision: plan.revision)
+      end
+      Renderer.write_plan(plan, config: config)
+      plan.missing_approvals
+    end
+
+    def reject_plan(plan, role:, note:)
+      decide(plan, role: role, decision: "rejected", note: note)
+      Workflow.plan_transition!(plan, "draft")
+      plan.log!("plan.changes_requested", actor: actor, note: note)
+      Renderer.write_plan(plan, config: config)
+    end
+
+    # -- Tickets ----------------------------------------------------------------------------------
+
+    def draft_tickets(plan, instruction: nil)
+      require_status!(plan, %w[approved ticketed])
+      result = TicketGenerator.new(llm: llm, schema: schema, config: config).generate(plan, instruction: instruction)
+      raise GuardError, result.report.errors unless result.report.ok?
+
+      replace_tickets(plan, result)
+      Renderer.write_plan(plan, config: config)
+      result
+    end
+
+    def approve_tickets(plan, role:, note: nil)
+      require_status!(plan, %w[ticketed])
+      decide(plan, role: "tickets:#{role}", decision: "approved", note: note)
+      return plan.missing_ticket_approvals if plan.missing_ticket_approvals.any?
+
+      Plan.transaction do
+        plan.tickets.each { |ticket| Workflow.ticket_transition!(ticket, "approved") }
+        Workflow.plan_transition!(plan, "tickets_approved")
+        plan.log!("tickets.approved", actor: actor, count: plan.tickets.size)
+      end
+      sync_issues(plan) if config.sync_issues
+      Renderer.write_plan(plan, config: config)
+      []
+    end
+
+    def sync_issues(plan)
+      plan.tickets.reject(&:issue_number).each do |ticket|
+        issue = github.create_issue(title: "[#{ticket.reference}] #{ticket.title}", body: issue_body(ticket),
+                                    labels: config.issue_labels + [plan.key.downcase, ticket.kind])
+        ticket.update!(issue_number: issue["number"])
+        plan.log!("ticket.issue_created", actor: actor, ticket: ticket, issue: issue["number"])
+      end
+    end
+
+    # -- Development ------------------------------------------------------------------------------
+
+    # Ready tickets, within the parallel agent limit, optionally narrowed to the given keys.
+    def startable(plan, only: nil)
+      capacity = [config.max_parallel_agents - plan.tickets.count(&:active_agent?), 0].max
+      candidates = plan.tickets.select(&:ready?)
+      keys = Array(only).map(&:upcase)
+      candidates = candidates.select { |ticket| keys.include?(ticket.key) } if keys.any?
+      candidates.first(capacity)
+    end
+
+    def develop(plan, only: nil)
+      require_status!(plan, %w[tickets_approved in_development])
+      launched = startable(plan, only: only).map { |ticket| launch(ticket) }
+      Workflow.plan_transition!(plan, "in_development") if launched.any? && plan.status == "tickets_approved"
+      launched
+    end
+
+    def launch(ticket, prompt: AgentPrompt.new(ticket, config: config))
+      agent, run = agents.launch(prompt: prompt.to_s, repo_url: github.repo_url, name: prompt.pr_title)
+      Workflow.ticket_transition!(ticket, "running")
+      ticket.update!(agent_id: agent["id"], agent_run_id: run.id, agent_url: agent["url"])
+      ticket.plan.log!("ticket.agent_started", actor: actor, ticket: ticket, agent: agent["id"], run: run.id)
+      ticket
+    end
+
+    # Polls running agents and open pull requests, moving tickets along as work lands.
+    def refresh(plan)
+      plan.tickets.each do |ticket|
+        case ticket.status
+        when "running" then refresh_agent(ticket)
+        when "pr_open", "pr_approved" then refresh_pull(ticket)
+        end
+      end
+      finish(plan)
+      plan.tickets.reset
+    end
+
+    def review(ticket)
+      require_ticket_status!(ticket, %w[pr_open pr_approved])
+      pull = github.pull(ticket.pr_number)
+      files = github.pull_files(ticket.pr_number)
+      features = feature_files(files, pull.dig("head", "sha"))
+      checks = github.checks(pull.dig("head", "sha"))
+      report = Guards::PrGuard.new(ticket, pull: pull, files: files, checks: checks, features: features,
+                                           behind: github.behind_by(pull), config: config).call
+      ticket.update!(guard_report: report.to_h)
+      ticket.plan.log!("ticket.reviewed", actor: actor, ticket: ticket, errors: report.errors.size,
+                                          warnings: report.warnings.size)
+      report
+    end
+
+    def approve_pr(ticket, note: nil)
+      report = review(ticket)
+      raise GuardError, report.errors unless report.ok?
+
+      decide(ticket, role: "pr", decision: "approved", note: note)
+      Workflow.ticket_transition!(ticket, "pr_approved") if ticket.status == "pr_open"
+      ticket.plan.log!("ticket.pr_approved", actor: actor, ticket: ticket, pr: ticket.pr_number)
+      github.review(ticket.pr_number, body: "Approved in plan-driven by #{actor}. #{note}".strip)
+      report
+    end
+
+    def request_changes(ticket, feedback)
+      require_ticket_status!(ticket, %w[pr_open pr_approved failed])
+      decide(ticket, role: "pr", decision: "rejected", note: feedback) unless ticket.status == "failed"
+      Workflow.ticket_transition!(ticket, "changes_requested") unless ticket.status == "failed"
+      run = agents.follow_up(ticket.agent_id, follow_up_prompt(ticket, feedback))
+      Workflow.ticket_transition!(ticket, "running")
+      ticket.update!(agent_run_id: run.id)
+      ticket.plan.log!("ticket.changes_requested", actor: actor, ticket: ticket, feedback: feedback, run: run.id)
+      ticket
+    end
+
+    def merge(ticket)
+      require_ticket_status!(ticket, %w[pr_approved])
+      require_mergeable!(ticket)
+      github.ready_for_review(ticket.pr_number) if github.pull(ticket.pr_number)["draft"]
+      result = github.merge(ticket.pr_number, title: "#{ticket.title} (#{ticket.reference})",
+                                              method: config.merge_method)
+      ticket.update!(merged_sha: result["sha"])
+      Workflow.ticket_transition!(ticket, "merged")
+      ticket.plan.log!("ticket.merged", actor: actor, ticket: ticket, sha: result["sha"])
+      finish(ticket.plan)
+      ticket
+    end
+
+    # -- Evidence and report ----------------------------------------------------------------------
+
+    def evidence(plan, command: nil)
+      Evidence.run_cucumber(plan, actor: actor, command: command)
+    end
+
+    def report(plan)
+      plan.log!("report.written", actor: actor)
+      Renderer.write_report(plan, config: config)
+    end
+
+    private
+
+    def require_mergeable!(ticket)
+      report = review(ticket)
+      raise GuardError, report.errors unless report.ok?
+      return unless report.warnings.any? { |warning| warning.include?("still running") }
+
+      raise GuardError, ["CI is still running; wait for it to finish"]
+    end
+
+    def decide(record, role:, decision:, note:)
+      plan = record.is_a?(Plan) ? record : record.plan
+      if record.is_a?(Plan) && !role.start_with?("tickets:")
+        require_status!(plan, %w[in_review])
+        allowed = config.plan_approvals.map(&:to_s)
+        unless allowed.include?(role.to_s)
+          raise ArgumentError,
+                "unknown role #{role}; this project approves as #{allowed.join(", ")}"
+        end
+      end
+      record.approvals.create!(role: role.to_s, decision: decision, actor: actor, note: note, revision: plan.revision)
+    end
+
+    def refresh_agent(ticket)
+      run = agents.run(ticket.agent_id, ticket.agent_run_id)
+      return unless run.terminal?
+
+      if run.finished? && run.pr_url
+        ticket.update!(pr_url: run.pr_url, pr_number: GitHub.pr_number(run.pr_url), branch: run.branch)
+        Workflow.ticket_transition!(ticket, "pr_open")
+        ticket.plan.log!("ticket.pr_opened", actor: "cursor-agent", ticket: ticket, pr: run.pr_url)
+      else
+        Workflow.ticket_transition!(ticket, "failed")
+        ticket.plan.log!("ticket.agent_failed", actor: "cursor-agent", ticket: ticket, status: run.status,
+                                                result: run.result.to_s[0, 500])
+      end
+    end
+
+    def refresh_pull(ticket)
+      pull = github.pull(ticket.pr_number)
+      return unless pull["merged"]
+
+      ticket.update!(merged_sha: pull["merge_commit_sha"])
+      Workflow.ticket_transition!(ticket, "merged")
+      ticket.plan.log!("ticket.merged", actor: pull.dig("merged_by", "login") || "github", ticket: ticket,
+                                        sha: pull["merge_commit_sha"], outside_plan_driven: true)
+    end
+
+    def finish(plan)
+      plan.tickets.reset
+      return unless plan.status == "in_development" && plan.tickets.all? { |ticket| ticket.status == "merged" }
+
+      Workflow.plan_transition!(plan, "delivered")
+      plan.log!("plan.delivered", actor: actor)
+    end
+
+    def feature_files(files, sha)
+      files.select { |file| file["filename"].end_with?(".feature") && file["status"] != "removed" }
+           .to_h { |file| [file["filename"], github.file(file["filename"], ref: sha)] }
+    end
+
+    def follow_up_prompt(ticket, feedback)
+      report = Guards::Report.from_h(ticket.guard_report)
+      checks = if report.errors.any?
+                 "\n\nThe automated checks also found:\n#{report.errors.map do |e|
+                   "- #{e}"
+                 end.join("\n")}"
+               else
+                 ""
+               end
+      "Review feedback on the pull request for #{ticket.reference}:\n\n#{feedback}#{checks}\n\n" \
+        "Push the fixes to the same branch. Keep the pull request title and description format."
+    end
+
+    def issue_body(ticket)
+      criteria = ticket.criteria.each_with_index.map { |criterion, index| "- [ ] #{index + 1}. #{unlinked(criterion)}" }
+      notes = ticket.implementation_notes.presence
+      <<~MD
+        #{unlinked(ticket.story)}
+
+        #{unlinked(ticket.description)}
+
+        ### Acceptance criteria
+        #{criteria.join("\n")}
+        #{"\n### Implementation notes\n#{unlinked(notes)}\n" if notes}
+        ---
+        Plan #{ticket.plan.key}: #{ticket.plan.title} · kind: #{ticket.kind} · estimate: #{ticket.estimate}
+        #{"· depends on #{ticket.dependencies.join(", ")}" if ticket.dependencies.any?}
+      MD
+    end
+
+    # GitHub links "#1" and "@name" anywhere outside code, so "You're #1 on the waitlist" would point
+    # at an unrelated pull request and "(@event)" would mention a user. An empty comment breaks
+    # the link and renders nothing.
+    def unlinked(text)
+      text.to_s.split(/(```.*?```|`[^`\n]*`)/m).each_with_index.map do |part, index|
+        index.odd? ? part : part.gsub(/(?<![\w&])([#@])(?=\w)/, '\1<!-- -->')
+      end.join
+    end
+
+    def replace_tickets(plan, result)
+      Plan.transaction do
+        plan.tickets.destroy_all
+        result.tickets.each { |attributes| plan.tickets.create!(ticket_attributes(attributes)) }
+        Workflow.plan_transition!(plan, "ticketed") if plan.status == "approved"
+        plan.log!("tickets.drafted", actor: actor, count: result.tickets.size, attempts: result.attempts,
+                                     fixes: result.report.fixes, warnings: result.report.warnings)
+      end
+      plan.tickets.reset
+    end
+
+    def ticket_attributes(attributes)
+      {
+        key: attributes["key"], position: attributes["position"], title: attributes["title"],
+        kind: attributes["kind"], ticket_type: attributes["type"], story: attributes["story"],
+        description: attributes["description"], acceptance_criteria: attributes["acceptance_criteria"],
+        implementation_notes: attributes["implementation_notes"], estimate: attributes["estimate"],
+        depends_on: attributes["depends_on"], touches: attributes["touches"]
+      }
+    end
+
+    def require_status!(plan, statuses)
+      return if statuses.include?(plan.status)
+
+      raise TransitionError, "plan #{plan.key} is #{plan.status} (#{Workflow::PLAN_DESCRIPTIONS[plan.status]})"
+    end
+
+    def require_ticket_status!(ticket, statuses)
+      return if statuses.include?(ticket.status)
+
+      raise TransitionError, "ticket #{ticket.reference} is #{ticket.status}; this needs #{statuses.join(" or ")}"
+    end
+
+    def drafter
+      Drafter.new(llm: llm, schema: schema, config: config)
+    end
+
+    def llm
+      @llm ||= LLM.new(config)
+    end
+
+    def schema
+      @schema ||= SchemaContext.new
+    end
+
+    def github
+      @github ||= GitHub.new
+    end
+
+    def agents
+      @agents ||= CursorAgents.new(config: config)
+    end
+  end
+end

data/lib/plan_driven/drafter.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Turns interview answers into the drafted sections of a plan, then keeps the model honest:
+  # the guard runs on every draft, and its errors go back to the model as a list to fix.
+  class Drafter
+    Result = Struct.new(:sections, :report, :attempts, :assumptions, keyword_init: true)
+
+    def initialize(llm: LLM.new, schema: SchemaContext.new, config: PlanDriven.configuration)
+      @llm = llm
+      @schema = schema
+      @config = config
+      @template = config.template
+    end
+
+    def draft(answers, title:)
+      answers = answers.transform_keys(&:to_s)
+      messages = [{ role: "user", content: request(answers, title) }]
+      attempts = 0
+
+      loop do
+        attempts += 1
+        reply = @llm.chat(system: system_prompt, messages: messages)
+        begin
+          parsed = 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
+        sections = answers.merge(parsed.fetch("sections", {}).slice(*@template.drafted.map(&:key)))
+        report = Guards::PlanGuard.new(sections, schema: @schema, template: @template).call
+        if report.ok? || attempts > @config.max_repair_attempts
+          return Result.new(sections: sections, report: report, attempts: attempts,
+                            assumptions: Array(parsed["assumptions"]))
+        end
+
+        messages += [{ role: "assistant", content: reply.text }, { role: "user", content: repair(report) }]
+      end
+    end
+
+    # One section again, with an instruction from the reviewer ("shorter", "add the index").
+    def redraft(sections, key, instruction)
+      section = @template[key] or raise ArgumentError, "unknown section #{key}"
+      content = <<~TEXT
+        The current plan, as JSON:
+        #{JSON.pretty_generate(sections)}
+
+        Rewrite only the section "#{section.key}" (#{section.title}). Reviewer's instruction: #{instruction}
+        Guidance for this section: #{section.guidance}
+        Reply with JSON: {"sections": {"#{section.key}": "..."}}
+      TEXT
+      reply = @llm.chat(system: system_prompt, messages: [{ role: "user", content: content }])
+      parse(reply.text).dig("sections", section.key).to_s
+    end
+
+    def system_prompt
+      <<~PROMPT
+        You write implementation plans for a Ruby on Rails team. A plan is read by developers,
+        QA, DevOps and a director, then split into tickets that coding agents implement.
+
+        Write in plain, specific English. Name real models, tables, columns and file paths.
+        Follow Rails conventions. Changes are additive and legacy-safe: expand, dual write,
+        backfill, switch reads, then contract. Never describe something as existing unless it
+        is in the schema you are given. When you don't know, say so under Outstanding questions.
+
+        Reply with one JSON object and nothing else:
+        {"sections": {"<key>": "<markdown>", ...}, "assumptions": ["..."]}
+
+        Sections to write, by key:
+        #{@template.drafted.map { |section| "- #{section.key} (#{section.title}): #{section.guidance}" }.join("\n")}
+      PROMPT
+    end
+
+    private
+
+    def request(answers, title)
+      asked = @template.asked.filter_map do |section|
+        value = answers[section.key].to_s.strip
+        "#{section.title}:\n#{value}" unless value.empty?
+      end
+      <<~TEXT
+        Plan title: #{title}
+
+        The team's answers:
+        #{asked.join("\n\n")}
+
+        The application's schema:
+        #{@schema.to_prompt}
+        #{"\nMore context:\n#{@config.extra_context}" if @config.extra_context}
+      TEXT
+    end
+
+    def repair(report)
+      <<~TEXT
+        The plan was checked and these problems must be fixed:
+        #{report.errors.map { |error| "- #{error}" }.join("\n")}
+
+        Reply with the full JSON again, every section included.
+      TEXT
+    end
+
+    def parse(text)
+      parsed = JsonReply.parse(text)
+      raise InvalidResponseError, "the reply had no \"sections\" object" unless parsed["sections"].is_a?(Hash)
+
+      parsed["sections"] = parsed["sections"].transform_values { |value| stringify(value) }
+      parsed
+    end
+
+    def stringify(value)
+      case value
+      when Array then value.map { |item| "- #{item}" }.join("\n")
+      when Hash then value.map { |heading, body| "### #{heading}\n#{stringify(body)}" }.join("\n\n")
+      else value.to_s
+      end
+    end
+  end
+end

data/lib/plan_driven/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ProviderError < Error; end
+  class InvalidResponseError < Error; end
+
+  # A phase transition that the workflow doesn't allow, such as generating tickets for a plan
+  # nobody has approved.
+  class TransitionError < Error; end
+
+  # A guard found problems that block the next step. `problems` holds the messages.
+  class GuardError < Error
+    attr_reader :problems
+
+    def initialize(problems, message = nil)
+      @problems = Array(problems)
+      super(message || "#{@problems.size} problem(s) block this step:\n#{@problems.map { |p| "  - #{p}" }.join("\n")}")
+    end
+  end
+end

data/lib/plan_driven/evidence.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+
+module PlanDriven
+  # Proof that the delivered code does what the plan promised: every acceptance criterion maps to
+  # a Cucumber scenario tagged `@<plan>-<ticket> @ac-N`, and the scenarios' results are stored with
+  # the commit they ran against.
+  module Evidence
+    Row = Struct.new(:ticket, :number, :criterion, :scenarios, keyword_init: true) do
+      def status
+        return "no scenario" if scenarios.empty?
+        return "passed" if scenarios.all? { |scenario| scenario["status"] == "passed" }
+
+        scenarios.any? { |scenario| scenario["status"] == "failed" } ? "failed" : "not run"
+      end
+    end
+
+    module_function
+
+    def tag_expression(plan)
+      plan.tickets.map(&:feature_tag).join(" or ")
+    end
+
+    def run_cucumber(plan, actor:, command: nil, root: PlanDriven.configuration.root_path)
+      Dir.mktmpdir do |dir|
+        out = File.join(dir, "cucumber.json")
+        shown = command&.join(" ") || %(bundle exec cucumber --tags "#{tag_expression(plan)}")
+        command ||= ["bundle", "exec", "cucumber", "--tags", tag_expression(plan), "--format", "json", "--out", out,
+                     "--format", "progress"]
+        output, status = Open3.capture2e(*command, chdir: root.to_s)
+        json = File.exist?(out) ? File.read(out) : "[]"
+        record(plan, json, command: shown, actor: actor, exit_ok: status.success?, output: output)
+      end
+    end
+
+    def record(plan, json, command:, actor:, exit_ok: true, output: nil)
+      scenarios = parse(json)
+      status = if scenarios.empty? then "no scenarios"
+               elsif exit_ok && scenarios.all? { |scenario| scenario["status"] == "passed" } then "passed"
+               else "failed"
+               end
+      run = plan.evidence_runs.create!(kind: "cucumber", command: command, status: status,
+                                       commit_sha: Repository.head_sha,
+                                       results: { "scenarios" => scenarios, "output" => output.to_s.last(4000) })
+      plan.log!("evidence.recorded", actor: actor, status: status, scenarios: scenarios.size)
+      run
+    end
+
+    # Cucumber's JSON formatter: features -> elements (scenarios) -> steps with results.
+    def parse(json)
+      Array(JSON.parse(json.to_s.strip.empty? ? "[]" : json)).flat_map do |feature|
+        feature_tags = Array(feature["tags"]).map { |tag| tag["name"] }
+        Array(feature["elements"]).select { |element| element["type"] == "scenario" }.map do |element|
+          tags = (feature_tags + Array(element["tags"]).map { |tag| tag["name"] }).uniq
+          { "name" => element["name"], "tags" => tags, "file" => "#{feature["uri"]}:#{element["line"]}",
+            "status" => scenario_status(element) }
+        end
+      end
+    rescue JSON::ParserError
+      []
+    end
+
+    def scenario_status(element)
+      statuses = (Array(element["before"]) + Array(element["steps"]) + Array(element["after"]))
+                 .map { |step| step.dig("result", "status") }
+      return "failed" if statuses.include?("failed")
+      return "passed" if statuses.any? && statuses.all? { |status| %w[passed skipped].include?(status) } &&
+                         Array(element["steps"]).all? { |step| step.dig("result", "status") == "passed" }
+
+      "not run"
+    end
+
+    def matrix(plan)
+      scenarios = plan.evidence_runs.last&.scenarios || []
+      plan.tickets.flat_map do |ticket|
+        ticket.criteria.each_with_index.map do |criterion, index|
+          matching = scenarios.select do |scenario|
+            scenario["tags"].include?(ticket.feature_tag) && scenario["tags"].include?("@ac-#{index + 1}")
+          end
+          Row.new(ticket: ticket, number: index + 1, criterion: criterion, scenarios: matching)
+        end
+      end
+    end
+
+    def matrix_markdown(plan)
+      run = plan.evidence_runs.last
+      return "No test evidence recorded yet. Run `plan-driven evidence #{plan.key}`." unless run
+
+      rows = matrix(plan).map do |row|
+        scenario = row.scenarios.map { |s| "#{s["name"]} (`#{s["file"]}`)" }.join("; ").presence || "-"
+        ["#{row.ticket.key}.#{row.number}", row.criterion, scenario, row.status]
+      end
+      commit = run.commit_sha.present? ? " on commit `#{run.commit_sha[0, 7]}`" : ""
+      intro = "Cucumber, run #{run.created_at.strftime("%-d %b %Y %H:%M")}#{commit}: `#{run.command}`"
+      "#{intro}\n\n#{Renderer::Markdown.table(%w[AC Criterion Scenario Result], rows)}"
+    end
+
+    def summary_line(plan)
+      return "No test evidence recorded yet." unless plan.evidence_runs.any?
+
+      rows = matrix(plan)
+      passed = rows.count { |row| row.status == "passed" }
+      "#{passed} of #{rows.size} acceptance criteria are proven by a passing scenario."
+    end
+  end
+end

data/lib/plan_driven/gherkin.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PlanDriven
+  # Just enough Gherkin to know which scenarios exist and how they're tagged. Tags on the
+  # Feature line apply to every scenario in it, as they do in Cucumber.
+  module Gherkin
+    Scenario = Struct.new(:name, :tags, :line, :path, :steps, keyword_init: true)
+    Feature = Struct.new(:name, :tags, :path, :scenarios, keyword_init: true)
+
+    SCENARIO = /\A\s*(Scenario(?: Outline| Template)?|Example):\s*(.*)\z/
+    FEATURE = /\A\s*(Feature|Ability|Business Need):\s*(.*)\z/
+    STEP = /\A\s*(Given|When|Then|And|But|\*)\s+(.*)\z/
+
+    module_function
+
+    def parse(text, path: nil)
+      state = { feature: Feature.new(name: nil, tags: [], path: path, scenarios: []), tags: [], scenario: nil }
+      text.to_s.each_line.with_index(1) { |raw, number| read_line(state, raw.strip, number) }
+      state[:feature]
+    end
+
+    def read_line(state, line, number)
+      return if line.empty? || line.start_with?("#")
+
+      feature = state[:feature]
+      if line.start_with?("@")
+        state[:tags].concat(line.split(/\s+/).grep(/\A@/))
+      elsif (match = line.match(FEATURE))
+        feature.name = match[2].strip
+        feature.tags = state.delete(:tags)
+        state[:tags] = []
+      elsif (match = line.match(SCENARIO))
+        state[:scenario] = Scenario.new(name: match[2].strip, tags: (feature.tags + state[:tags]).uniq, line: number,
+                                        path: feature.path, steps: [])
+        feature.scenarios << state[:scenario]
+        state[:tags] = []
+      elsif state[:scenario] && (match = line.match(STEP))
+        state[:scenario].steps << "#{match[1]} #{match[2]}"
+      end
+    end
+  end
+end