openlanes 3.0.1 → 3.1.0

data/lib/openlanes.rb

@@ -6,7 +6,10 @@ require "dry/cli"
 require "dry/cli/help"
 
 require "dry/inflector"
+# Every command workflow answers a Dry::Monads::Result (see OpenLanes::Refusal).
+require "dry/monads"
 require "fileutils"
+require "open3"
 require "shellwords"
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
@@ -21,13 +24,16 @@ loader.inflector.inflect(
   "ui"         => "UI"
 )
 loader.collapse("#{__dir__}/openlanes/support")
+loader.collapse("#{__dir__}/openlanes/cli/coverage")
 loader.collapse("#{__dir__}/openlanes/cli/create")
 loader.collapse("#{__dir__}/openlanes/cli/docs")
 loader.collapse("#{__dir__}/openlanes/cli/eval")
 loader.collapse("#{__dir__}/openlanes/cli/index")
 loader.collapse("#{__dir__}/openlanes/cli/init")
 loader.collapse("#{__dir__}/openlanes/cli/list_plans")
+loader.collapse("#{__dir__}/openlanes/cli/review")
 loader.collapse("#{__dir__}/openlanes/cli/run")
+loader.collapse("#{__dir__}/openlanes/cli/setup")
 loader.collapse("#{__dir__}/openlanes/cli/start")
 loader.collapse("#{__dir__}/openlanes/cli/states")
 loader.collapse("#{__dir__}/openlanes/cli/unblock")
@@ -40,9 +46,13 @@ loader.collapse("#{__dir__}/openlanes/cli/mail/subcommands")
 loader.collapse("#{__dir__}/openlanes/cli/state/subcommands")
 loader.collapse("#{__dir__}/openlanes/cli/resync/subcommands")
 loader.collapse("#{__dir__}/openlanes/cli/skills/subcommands")
+loader.collapse("#{__dir__}/openlanes/cli/api/subcommands")
+loader.ignore("#{__dir__}/openlanes/cli/api/api.rb")
+loader.collapse("#{__dir__}/openlanes/cli/app/subcommands")
 loader.ignore("#{__dir__}/openlanes/cli/linear/linear.rb")
 loader.ignore("#{__dir__}/openlanes/cli/mail/mail.rb")
 loader.ignore("#{__dir__}/openlanes/cli/state/state.rb")
+loader.ignore("#{__dir__}/openlanes/cli/app/app.rb")
 loader.ignore("#{__dir__}/openlanes/linear/mapping.rb")
 loader.setup
 
@@ -51,8 +61,8 @@ loader.setup
 # Three phases, each with a file that proves it happened, and a guarded state
 # machine that refuses to let a plan folder claim a phase it has not reached.
 #
-#   spec   ⚪️ New          spec.md
-#   plan   ⭐️ Ready        plan.md
+#   spec   ⚪ New          spec.md
+#   plan   ⭐ Ready        plan.md
 #   build  🟡 → ✅         pull-requests.md
 #
 # The conventions are not documented anywhere else by hand: the status
@@ -95,6 +105,8 @@ module OpenLanes
   def self.move_directory(source, target)
     return false if File.exist?(target)
 
+    # Into archive/ and friends, which the first move there creates.
+    FileUtils.mkdir_p(File.dirname(target))
     parent = File.dirname(source)
     tracked = system("git",
       "-C",
@@ -116,7 +128,8 @@ module OpenLanes
     true
   end
 
-  # Plan numbers visible in `.plans` on a git ref, without checking it out.
+  # Plan numbers visible in `.plans` on a git ref, without checking it out,
+  # the inactive subfolders included: an archived plan keeps its number.
   #
   # A pull request's branch is the only place that knows how far the sequence
   # had got when the work started, and branches are not all rebased onto the
@@ -127,14 +140,39 @@ module OpenLanes
   # @return [Array<OpenLanes::Plans::Ordinal>] possibly empty
   def self.plans_on_ref(root, ref)
     ["origin/#{ref}", ref].each do |candidate|
-      out = `git -C #{root.shellescape} ls-tree -d --name-only #{candidate.shellescape} #{PLANS_DIR}/ 2>/dev/null`
-      next if out.to_s.strip.empty?
-
-      return out.lines.filter_map { |line| Plans::Ordinal.from_dirname(File.basename(line.strip)) }
+      found = plans_at(root, candidate)
+      return found unless found.empty?
     end
     []
   end
 
+  # Plan numbers in `.plans` on one tree-ish, the inactive subfolders
+  # included. {plans_on_ref} guesses at a branch name; this reads exactly
+  # what it is given, which is what allocating a number across every branch
+  # needs: a full ref name tried as `origin/refs/heads/x` would cost a
+  # second `ls-tree` per branch for nothing.
+  #
+  # @param root [String] any directory inside the repository
+  # @param treeish [String] a ref, or a commit
+  # @param plans [String] the `.plans` directory, relative to +root+
+  # @return [Array<OpenLanes::Plans::Ordinal>] empty when the ref is unknown
+  #   or carries no plans
+  def self.plans_at(root, treeish, plans: PLANS_DIR)
+    dirs = [plans, *Plans::Tree::SUBFOLDERS.map { "#{plans}/#{it}" }].map { "#{it}/" }
+    out, status = Open3.capture2("git",
+      "-C",
+      root,
+      "ls-tree",
+      "-d",
+      "--name-only",
+      treeish,
+      *dirs,
+      err: File::NULL)
+    return [] unless status.success?
+
+    out.lines.filter_map { |line| Plans::Ordinal.from_dirname(File.basename(line.strip)) }
+  end
+
   # The agent that writes a specification for work that already shipped.
   # Named here rather than in the CLI so the definition file stays the single
   # source of truth about who does what.

data/openlanes.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
   TEXT
   spec.homepage = "https://github.com/kigster/openlanes"
 
-  spec.required_ruby_version = ">= 3" # rubocop:disable Gemspec/RequiredRubyVersion -- the floor users get, not the Ruby the cops lint for
+  spec.required_ruby_version = ">= 4" # rubocop:disable Gemspec/RequiredRubyVersion -- the floor users get, not the Ruby the cops lint for
 
   spec.metadata = {
     "homepage_uri"          => spec.homepage,
@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
     # `openlanes web --demo` replays.
     # Source maps stay out: they double the page's size for nobody who installs it.
     globbed = Dir.glob(["*.gemspec", "lib/**/*.rb", "agents/*.md", "schemas/*.json", "evals/cases/**/*", "skills/**/*",
-                        "exe/*", "bin/*", "web/dist/**/*", "web/src/api/fixtures/board.json"])
+                        "exe/*", "web/dist/**/*", "web/src/api/fixtures/board.json", "Brewfile"])
     globbed.select { |f| File.file?(f) && !f.end_with?(".map") }
   end
 
@@ -49,10 +49,10 @@ Gem::Specification.new do |spec|
   end
 
   spec.bindir = "exe"
-  # `depot` and `lanes` are symlinks to `openlanes` in the checkout; named here
+  # `ol` and `lanes` are symlinks to `openlanes` in the checkout; named here
   # so that installing the gem writes all three, rather than only the one git
   # recorded.
-  spec.executables = %w[openlanes depot lanes]
+  spec.executables = %w[openlanes ol lanes]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "aasm"
@@ -66,6 +66,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "dry-inflector"
   spec.add_dependency "dry-monads"
   spec.add_dependency "fuzzy-string-match"
+  spec.add_dependency "inquirex-llm", "~> 0.12"
   # Opens the control room in the browser when `openlanes run` starts the API server.
   spec.add_dependency "launchy", "~> 3.1"
   spec.add_dependency "parallel"
@@ -76,7 +77,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency "rackup", "~> 2.1"
   # The live run (plan 004) lives in Redis: board and command streams, plan claims.
   spec.add_dependency "redis-client", "~> 0.31"
+  spec.add_dependency "semantic_logger", "~> 5.1"
   spec.add_dependency "sinatra", "~> 4.2"
+  spec.add_dependency "agent-lock"
   spec.add_dependency "tty-box"
   spec.add_dependency "tty-command"
   spec.add_dependency "tty-cursor"
@@ -84,4 +87,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "tty-screen"
   spec.add_dependency "unicode-display_width"
   spec.add_dependency "zeitwerk"
+  spec.add_dependency "newrelic_rpm"
+  spec.add_dependency "newrelic-infinite_tracing"
 end

data/schemas/journal-event.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/kigster/openlanes/schemas/journal-event.schema.json",
+  "title": "openlanes engine journal event",
+  "description": "One line of a node's NDJSON progress journal, written by OpenLanes::Engine::EventJournal under Runtime.journal_dir. Append-only, fsync'd per event.",
+  "type": "object",
+  "required": ["v", "seq", "at", "node", "run_id", "kind"],
+  "properties": {
+    "v": { "const": 1 },
+    "seq": { "type": "integer", "minimum": 1 },
+    "at": { "type": "string", "format": "date-time" },
+    "node": { "type": "string", "minLength": 1 },
+    "run_id": { "type": "string", "minLength": 1 },
+    "kind": {
+      "enum": [
+        "run_started", "run_ended", "plan_assigned", "agent_started", "agent_session",
+        "agent_offset", "agent_ended", "transition", "extension", "question"
+      ]
+    },
+    "plan": { "type": "string", "pattern": "^\\d{3}\\.\\d{2}$" },
+    "agent": { "type": "string", "minLength": 1 },
+    "round": { "type": "integer", "minimum": 0 },
+    "pid": { "type": "integer", "minimum": 1 },
+    "started_at": { "type": ["string", "null"], "format": "date-time" },
+    "session_id": { "type": ["string", "null"] },
+    "output_file": { "type": ["string", "null"] },
+    "offset": { "type": "integer", "minimum": 0 },
+    "exit": { "type": ["integer", "null"] },
+    "from": { "type": "string" },
+    "to": { "type": "string" },
+    "event": { "type": "string" },
+    "seconds": { "type": "number", "minimum": 0 },
+    "note": { "type": "string" },
+    "reason": { "type": "string" },
+    "jobs": { "type": "integer", "minimum": 1 },
+    "isolation": { "type": "string" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "kind": { "const": "plan_assigned" } } },
+      "then": { "required": ["plan", "agent"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "agent_started" } } },
+      "then": { "required": ["plan", "agent", "pid", "started_at", "session_id", "output_file"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "agent_session" } } },
+      "then": { "required": ["plan", "agent", "session_id"], "properties": { "session_id": { "type": "string" } } }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "agent_offset" } } },
+      "then": { "required": ["plan", "agent", "offset"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "agent_ended" } } },
+      "then": { "required": ["plan", "agent", "exit"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "transition" } } },
+      "then": { "required": ["plan", "from", "to"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "extension" } } },
+      "then": { "required": ["plan", "agent", "seconds"] }
+    },
+    {
+      "if": { "properties": { "kind": { "const": "question" } } },
+      "then": { "required": ["plan", "agent", "note"] }
+    }
+  ]
+}

data/schemas/plan-state.schema.json

@@ -22,9 +22,41 @@
       "description": "The last state the harness moved the folder to. The folder name is authoritative.",
       "type": ["string", "null"]
     },
+    "moves": {
+      "description": "How many times openlanes has moved the folder to another state. A settling stage notes the count, so a later move, even away and back, is seen.",
+      "type": "integer",
+      "minimum": 0
+    },
     "updated_at": { "type": ["string", "null"], "format": "date-time" },
+    "quality_ask": {
+      "description": "R4's question, desired_codebase_quality, asked once per project on the first review-ok-not-perfect pull request while .openlanes.yml has no key; settled when a person answers.",
+      "type": "object",
+      "required": ["asked_at"],
+      "additionalProperties": false,
+      "properties": {
+        "asked_at": { "type": "string", "format": "date-time" },
+        "answer": { "type": "string", "enum": ["high", "mvp"] },
+        "by": { "type": "string", "minLength": 1 },
+        "settled_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "resume_until": {
+      "description": "Until when a 💣 on this plan does not halt the run: the control room's Resume anyway for 24 h.",
+      "type": ["string", "null"],
+      "format": "date-time"
+    },
+    "finished": {
+      "description": "When and how the plan finished: hansolo approved it, or its pull request merged. A merge replaces an approval. Cleared when an agent starts on the plan again, or a person rejects it.",
+      "type": "object",
+      "required": ["kind", "at"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["approved", "merged"] },
+        "at": { "type": "string", "format": "date-time" }
+      }
+    },
     "stages": {
-      "description": "One record per agent per round, written by the harness.",
+      "description": "One record per dispatch of an agent's round, in dispatch order, written by the harness.",
       "type": "array",
       "items": {
         "type": "object",
@@ -36,6 +68,7 @@
           "status": { "$ref": "#/$defs/status" },
           "from": { "type": "string" },
           "to": { "type": "string" },
+          "moves": { "description": "The plan's moves when this round settled.", "type": "integer", "minimum": 0 },
           "started_at": { "type": "string", "format": "date-time" },
           "finished_at": { "type": "string", "format": "date-time" },
           "adapter": { "enum": ["claude", "codex", "pi"] },
@@ -45,8 +78,17 @@
           "down": { "type": "integer", "minimum": 0 },
           "seconds": { "type": "number", "minimum": 0 },
           "note": { "type": "string" },
+          "session": {
+            "description": "The CLI's session id for this round, as soon as its stream named it. `claude --resume <id>`, run from `cwd`, carries it on by hand.",
+            "type": "string"
+          },
+          "cwd": {
+            "description": "The checkout the round ran in. A claude session is found only from the directory it ran in.",
+            "type": "string"
+          },
           "run": {
-            "description": "The harness process that dispatched it, so a restart can tell a crash from a live run.",
+            "description": "Deprecated: written by releases before 021.00, read so their crashes still resume. The harness pid and host now live in the run's state file outside the repository.",
+            "deprecated": true,
             "type": "object",
             "required": ["pid", "host"],
             "additionalProperties": false,
@@ -75,6 +117,84 @@
         }
       }
     },
+    "last-known-state": {
+      "description": "One resume record per agent, last one wins: written by the agent through `openlanes state resume`, or by the harness when the agent could not.",
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/agent" },
+      "additionalProperties": { "$ref": "#/$defs/lastKnownState" }
+    },
+    "merge_risk": {
+      "description": "palpatine-risk-assessor's verdicts for this visit to Completed (P1, P4), by pull request number, and when the engine rebased a sibling onto main (P5). Stands only while moves still equals the count it was written at.",
+      "type": "object",
+      "required": ["moves", "at", "verdicts", "rebased"],
+      "additionalProperties": false,
+      "properties": {
+        "moves": { "type": "integer", "minimum": 0 },
+        "at": { "type": "string", "format": "date-time" },
+        "verdicts": { "type": "object", "additionalProperties": { "enum": ["auto", "manual"] } },
+        "rebased": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" } }
+      }
+    },
+    "memory": {
+      "description": "Each agent's journal (M2): what it printed as one-line JSON while it worked, kept by the harness, the only writer. Entries are numbered 1 up across an agent's rounds, in order; a later one wins.",
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/agent" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["rounds"],
+        "additionalProperties": false,
+        "properties": {
+          "rounds": {
+            "description": "Keyed by the agent's journal round on this plan, 1 up across runs and states; not the dispatcher's round, which restarts in every run.",
+            "type": "object",
+            "propertyNames": { "pattern": "^[1-9][0-9]*$" },
+            "additionalProperties": { "$ref": "#/$defs/journalRound" }
+          }
+        }
+      }
+    },
+    "conversions": {
+      "description": "Questions in blocked.md the engine rewrote into lettered choices (D9), and ones it tried and could not, with the text as the agent wrote it.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["question", "digest", "original", "at", "model", "outcome"],
+        "additionalProperties": false,
+        "properties": {
+          "question": { "type": "integer", "minimum": 1, "description": "The n of ## Bn." },
+          "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA256 of original, so the same text is never sent twice." },
+          "original": { "type": "string", "minLength": 1 },
+          "at": { "type": "string", "format": "date-time" },
+          "model": { "type": "string", "minLength": 1 },
+          "outcome": { "enum": ["converted", "rejected"] },
+          "note": { "type": "string", "description": "Why the model's answer was rejected." }
+        }
+      }
+    },
+    "extensions": {
+      "description": "The harness asking a person for more time or another round for one agent (E1), and how each request was settled.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["number", "agent", "state", "round", "limit", "asked_at"],
+        "additionalProperties": false,
+        "properties": {
+          "number": { "type": "integer", "minimum": 1, "description": "The n of Xn, unique in this plan." },
+          "agent": { "type": "string", "minLength": 1 },
+          "state": { "type": "string", "minLength": 1, "description": "The status key the agent was working when it ran out." },
+          "round": { "type": "integer", "minimum": 1 },
+          "limit": { "enum": ["time", "rounds"], "description": "What ran out: the round's clock, or the agent's rounds." },
+          "asked_at": { "type": "string", "format": "date-time" },
+          "answer": { "enum": ["a", "b", "c"], "description": "a) one more round, b) ten more minutes, c) twenty more minutes." },
+          "by": { "type": "string", "minLength": 1, "description": "Who answered: a person's user name, or auto." },
+          "grant": { "enum": ["live", "round"], "description": "live: the running clock was extended; round: one more round." },
+          "seconds": { "type": "integer", "minimum": 0, "description": "Extra seconds on the clock the grant gives." },
+          "closed": { "type": "string", "minLength": 1, "description": "Why it was settled without an answer." },
+          "settled_at": { "type": "string", "format": "date-time" },
+          "spent": { "type": "boolean", "description": "A round grant's seconds were given to the round that ran on them." }
+        }
+      }
+    },
     "messages": {
       "description": "What agents on this plan said to each other, through `openlanes mail send`.",
       "type": "array",
@@ -83,17 +203,58 @@
         "required": ["number", "at", "from", "to", "body"],
         "additionalProperties": false,
         "properties": {
+          "id": { "type": "string", "minLength": 1, "description": "Written by `openlanes mail send`, so a message drained from Redis is recognised by identity, not by a number another copy of this file may also have given out. Absent on messages written before ids existed." },
           "number": { "type": "integer", "minimum": 1 },
           "at": { "type": "string", "format": "date-time" },
           "from": { "$ref": "#/$defs/agent" },
           "to": { "$ref": "#/$defs/agent" },
           "body": { "type": "string", "minLength": 1 },
+          "read": { "enum": ["yes", "no"], "description": "\"yes\" once its recipient ran `openlanes mail ack`. Absent on messages written before acks existed, which read as \"no\"." },
           "command": { "type": "string", "minLength": 1, "description": "The id of the page's command that sent it (plan 004, W13), so a redelivered command appends nothing twice." }
         }
       }
     }
   },
   "$defs": {
+    "lastKnownState": {
+      "description": "Where one agent stood when it was interrupted. No pid, token or exit field exists: those describe one machine's run and stay in openlanes-state.json.",
+      "type": "object",
+      "required": ["source", "at", "round", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "source": { "enum": ["agent", "harness"] },
+        "at": { "type": "string", "format": "date-time" },
+        "round": { "type": "integer", "minimum": 1 },
+        "status": { "$ref": "#/$defs/status" },
+        "done": { "type": "array", "items": { "type": "string" } },
+        "remaining": { "type": "array", "items": { "type": "string" } },
+        "next_step": { "type": "string" },
+        "files_touched": { "type": "array", "items": { "type": "string" } },
+        "note": { "type": "string" }
+      }
+    },
+    "journalRound": {
+      "type": "object",
+      "required": ["entries"],
+      "additionalProperties": false,
+      "properties": {
+        "round": { "type": "integer", "minimum": 1, "description": "The dispatcher's round it was printed in." },
+        "state": { "type": "string", "description": "The state the plan was in when the round started." },
+        "entries": { "type": "array", "items": { "$ref": "#/$defs/journalEntry" } }
+      }
+    },
+    "journalEntry": {
+      "type": "object",
+      "required": ["kind", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["todo", "done", "decision", "question", "override", "note"] },
+        "text": { "type": "string", "minLength": 1 },
+        "overrides": { "type": "integer", "minimum": 1, "description": "On an override: the number of the entry it overturns." },
+        "ref": { "type": "string", "pattern": "^B[0-9]+$", "description": "The blocked.md question this records, written by the harness." },
+        "answer": { "type": "string", "description": "A person's answer to that question, written by the harness." }
+      }
+    },
     "agent": { "type": "string", "pattern": "^[\\w-]+$" },
     "status": { "enum": ["Started", "Completed", "Almost completed", "Interrupted", "Blocked"] },
     "effort": { "enum": ["low", "medium", "high", "xhigh", "max", null] }

data/skills/openlanes/SKILL.md

@@ -28,10 +28,10 @@ description: The openlanes software factory (`openlanes` CLI) that drives `.plan
 
 ## The model in four facts
 
-- **The folder name is the state.** `.plans/003.00-⭐️ → tax-rule-dsl` is plan `003.00`, state Planned, slug `tax-rule-dsl`. There is no database. Folder names hold emoji and spaces, so quote every path. Refer to a plan by its ordinal (`003`, `003.01`) wherever a command accepts one.
+- **The folder name is the state.** `.plans/003.00━━⭐━━❯tax-rule-dsl` is plan `003.00`, state Planned, slug `tax-rule-dsl`. There is no database. Folder names hold emoji but no spaces; finished, deferred and discarded plans live in dated `.plans/archive/`, `deferred/` and `abandoned/` subfolders. Refer to a plan by its ordinal (`003`, `003.01`) wherever a command accepts one.
 - **Numbers are identity.** `NNN.00` is a new feature; `NNN.MM` with `MM > 0` documents work that already shipped (Retroactive). An ordinal is never renumbered.
 - **Lanes route a plan.** `full`: research, spec, plan, build, review. `plan`: the author's spec stands; plan, build, review. `quick`: one agent (`r2d2-mechanic`) does a short mechanical change, then review. The lane lives in `spec.md` frontmatter.
-- **Blocked means a human decides.** ⭕️ is a technical block (engineer), 🅱️ a product block (product). The questions sit in the plan's `blocked.md`; agents step around the plan until they are answered.
+- **Blocked means a human decides.** ⭕ is a technical block (engineer), 🛑 a product block (product). The questions sit in the plan's `blocked.md`; agents step around the plan until they are answered.
 
 Live references, never copied here so they cannot go stale:
 

data/skills/openlanes-documents/SKILL.md

@@ -21,12 +21,12 @@ Ask the tool, never a copy of its table:
 | File | For | Written by |
 | --- | --- | --- |
 | `spec.md` | what and why; its frontmatter says how to route and judge the work | `openlanes create`, the human, `leah-researcher` (`## Research`), `yoda-writer` |
-| `plan.md` | units, order, the integration check; blank means "waiting for the planner" | `yoda-writer` creates it empty, `palpatine-planner` fills it |
-| `plan-backend.md`, `plan-frontend.md` | each builder's units; a front-end file with no unit heading starts nobody | `palpatine-planner` |
+| `plan.md` | units under `## Backend` and `## Frontend`, order, the integration check; blank means "waiting for the planner"; a `## Frontend` with no unit heading starts nobody | `yoda-writer` creates it empty, `luthen-rael-planner` fills it |
+| `contract.md`, `openapi.yaml` | the interfaces between the halves; the HTTP surface when there is one | `luke-backend` |
 | `blocked.md` | open questions a human must decide | any agent, or a human |
 | `pull-requests.md` | the pull request table the review states are judged by | `openlanes run` when it opens the PR, `openlanes create --prs`, `openlanes resync prs` |
 | `rewrite.md`, `delayed.md`, `discarded.md`, `deployed.md`, `rollback.md` | why the plan left the main path | the reviewer (`rewrite.md`), otherwise a human |
-| `state.json` | stages, signatures, mailbox | the harness only; read it with `openlanes state show --plan <NNN>` |
+| `state.json` | stages, signatures, mailbox, read receipts, resume records (`last-known-state`) | the harness only; read it with `openlanes state show --plan <NNN>` |
 
 Agents also sign a ledger inside the document they own: a `> [!NOTE]` block of `[ agent: … status: Started, round 1 ]` lines. Leave those blocks as they are; the harness reads them to decide who finished.
 
@@ -36,7 +36,7 @@ Agents also sign a ledger inside the document they own: a `> [!NOTE]` block of `
 
 **blocked.md questions and answers.** A question is a line that starts with `B<n>`, after at most four `#` and an optional `**`: `## B1 — Which rate feed?`. Its answer is a heading `## A1` with the same number. Any other numbering (`1.`, `Q1`, a bullet `- B1`) is invisible: the folder never blocks, and `openlanes unblock` finds nothing to drain. Start no other line with `B` and a digit. An answer counts only when it names who decided (a role will do), carries a date, and picks one option.
 
-Which human a block waits on lives only in the emoji. `resync dirs` files a new `blocked.md` as ⭕️ (engineering); rename the folder's emoji to 🅱️ by hand when product owns the decision, and `resync` keeps it there.
+Which human a block waits on lives only in the emoji. `resync dirs` files a new `blocked.md` as ⭕ (engineering); rename the folder's emoji to 🛑 by hand when product owns the decision, and `resync` keeps it there.
 
 **pull-requests.md.** openlanes reads the first markdown table whose header names a pull request (`Pull Request Number`, `PR`, `#`) and whose rows link to `/pull/<n>`. Columns are found by header words: number, name or title, status. Status words: `Open`, `Draft` or `WIP`, `Merged`, `Closed`. Escape `[`, `]` and `|` inside a title. Prose below the table is ignored.
 

data/skills/openlanes-documents/references/blocked-template.md

@@ -1,6 +1,6 @@
 # blocked.md template
 
-A plan with `blocked.md` naming at least one open question is blocked: ⭕️ Technical Block (an engineer or the CTO decides) or 🅱️ Product Block (a product manager decides). Agents step around it until a human answers and runs `openlanes unblock <NNN>`, which hands the file to `lando-broker`. The broker folds each qualifying answer into `spec.md` (what and why) or `plan.md` (how and in what order), deletes the question with its answer, and deletes the file when nothing is left.
+A plan with `blocked.md` naming at least one open question is blocked: ⭕ Technical Block (an engineer or the CTO decides) or 🛑 Product Block (a product manager decides). Agents step around it until a human answers and runs `openlanes unblock <NNN>`, which hands the file to `lando-broker`. The broker folds each qualifying answer into `spec.md` (what and why) or `plan.md` (how and in what order), deletes the question with its answer, and deletes the file when nothing is left.
 
 Two heading kinds, and only these: `## B<n>` for a question, `## A<n>` for its answer. openlanes counts the `B` lines; a question numbered any other way blocks nothing.
 
@@ -45,5 +45,5 @@ Notes:
 
 - An answer counts only when it names who decided (a role is enough), carries a date, and picks one option. "Leaning towards B" stays, and so does its question.
 - Answer in pieces if that is how answers arrive; whatever is still open keeps the plan blocked.
-- A new `blocked.md` lands at ⭕️ on the next `openlanes resync dirs`. Rename the folder's emoji to 🅱️ when product owns the decision; nothing else records which human it waits on.
+- A new `blocked.md` lands at ⭕ on the next `openlanes resync dirs`. Rename the folder's emoji to 🛑 when product owns the decision; nothing else records which human it waits on.
 - `openlanes unblock <NNN> -n` lists the questions openlanes can see. Run it after writing the file.

data/skills/openlanes-documents/references/closing-templates.md

@@ -14,7 +14,7 @@ Dropped for good; terminal. Say why, so nobody re-proposes it blind.
 **What would change our minds:** a regulator requiring live rates.
 ```
 
-## delayed.md — ☢️ Deferred
+## delayed.md — 💤 Deferred
 
 The work could proceed and we chose not to yet. openlanes refuses the state unless the file names a **trigger** (it looks for the words trigger, revisit, when, until or once).
 

data/skills/openlanes-documents/references/plan-template.md

@@ -1,8 +1,8 @@
 # plan.md template
 
-`palpatine-planner` writes `plan.md` from a finished `spec.md`, plus `plan-backend.md` and `plan-frontend.md` holding each builder's units. Write it by hand only when you are taking the planner's place (lane `plan` skips research, not planning).
+`luthen-rael-planner` writes `plan.md` from a finished `spec.md`, with each builder's units under `## Backend` and `## Frontend`. Write it by hand only when you are taking the planner's place (lane `plan` skips research, not planning).
 
-`plan.md` stays **blank** until it is a plan: any `#`, `##` or `###` heading outside a ledger block tells openlanes the plan is written, and moves the folder from 📋 Ready for Planning to ⭐️ Planned. The whole plan lands as one pull request; more than eight units means the spec is several plans.
+`plan.md` stays **blank** until it is a plan: any `#`, `##` or `###` heading outside a ledger block tells openlanes the plan is written, and moves the folder from 📋 Ready for Planning to ⭐ Planned. The whole plan lands as one pull request; more than eight units means the spec is several plans.
 
 ```markdown
 # Rate Feed Sync — Plan
@@ -10,7 +10,7 @@
 **Spec:** `spec.md` in this folder
 **Depends on:** plans that must land first, by number, or nothing
 
-## Units
+## Backend
 
 ### U1 — Rates table and model
 
@@ -35,6 +35,14 @@
 - **Depends on:** U2
 - **Done when:** a real sync, nothing stubbed but the vendor's HTTP, stores rows the model reads back
 
+## Frontend
+
+No front-end units: the sync has no interface.
+
+## HTTP surface
+
+None, so no `openapi.yaml`.
+
 ## Order
 
 U1 → U2 → U3. Units that write the same file are sequential; say which can run in parallel and why.
@@ -56,6 +64,6 @@ U1 → U2 → U3. Units that write the same file are sequential; say which can r
 
 Notes:
 
-- Every unit appears in exactly one of `plan-backend.md` and `plan-frontend.md`, under its own `##` or `###` heading. `rey-frontend` starts only when `plan-frontend.md` has a unit heading, so a plan with no front end writes one plain line there and no heading.
+- Every unit appears in exactly one of `## Backend` and `## Frontend`, under its own `###` heading. `rey-frontend` starts only when `## Frontend` has a unit heading, so a plan with no front end writes one plain line there and no heading. Folders planned before plan 003 keep `plan-backend.md` and `plan-frontend.md`, which are still read.
 - `## Task completed when` and `## How to verify` are appended by the harness when missing; a section you wrote is left alone.
 - A plan stays one level above the code: signatures, routes and response shapes, not method bodies.

data/skills/openlanes-documents/references/retroactive-spec.md

@@ -36,7 +36,7 @@ If the pull requests merged after 018's folder was created and before 019's, the
 
 ## What happens next
 
-`create --prs` writes `pull-requests.md` (the folder is born 🕰️ Retroactive) and hands the folder to `yoda-writer`, which writes `spec.md` from the diff and an empty `plan.md`. `--no-spec` stops after recording the PRs. From there the plan moves like any other; `openlanes run -n --plan <NNN.MM>` shows who takes it next.
+`create --prs` writes `pull-requests.md` (the folder is born ⏪ Retroactive) and hands the folder to `yoda-writer`, which writes `spec.md` from the diff and an empty `plan.md`. `--no-spec` stops after recording the PRs. From there the plan moves like any other; `openlanes run -n --plan <NNN.MM>` shows who takes it next.
 
 ## What does not deserve one
 

data/skills/openlanes-run/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: openlanes-run
-description: Start the openlanes factory with `openlanes start` (engine plus control room, up until Stop All Local or Ctrl-C, questions answered and plans created on the page), or run openlanes's specialist agents to a fixed point with `openlanes run --until-settled` and clear blocked plans with `openlanes unblock`. Use when the user wants to start, run, resume or finish the agents, build or ship a plan, or unblock a ⭕️ / 🅱️ plan.
+description: Start the openlanes factory with `openlanes start` (engine plus control room, up until Stop All Local or Ctrl-C, questions answered and plans created on the page), or run openlanes's specialist agents to a fixed point with `openlanes run --until-settled` and clear blocked plans with `openlanes unblock`. Use when the user wants to start, run, resume or finish the agents, build or ship a plan, or unblock a ⭕ / 🛑 plan.
 ---
 
 # openlanes-run: drive the plans
@@ -9,7 +9,7 @@ Load the `openlanes` skill first if it is not in context.
 
 ## `openlanes start`: the factory with its control room
 
-`openlanes start` is the way to run the factory for a person. It is `openlanes run` with the control room on, and it does not stop at a fixed point: when a plan blocks, palpatine-planner's questions included, it idles, shows the questions in **Needs You** on the page, takes the answer from there, drains it, and hands the plan back to its agent. It picks up plans created on the page, by `openlanes create` in another terminal, or edited by hand, rescanning `.plans/` every 5 s (`--rescan`).
+`openlanes start` is the way to run the factory for a person. It is `openlanes run` with the control room on, and it does not stop at a fixed point: when a plan blocks, luthen-rael-planner's questions included, it idles, shows the questions in **Needs You** on the page, takes the answer from there, drains it, and hands the plan back to its agent. It picks up plans created on the page, by `openlanes create` in another terminal, or edited by hand, rescanning `.plans/` every 5 s (`--rescan`).
 
 ```bash
 openlanes start              # engine and control room on http://127.0.0.1:11000, browser opened
@@ -52,7 +52,7 @@ Keep the defaults (`--isolation worktree`, pushing on) whenever the user wants p
 openlanes run --until-settled --plan <NNN,...>
 ```
 
-A run takes minutes to hours: each agent may take up to 15 minutes per round, over several rounds. Start it in the background and wait for it to exit; it prints its progress log path at the start, which is what to read when the user asks how it is going. Avoid polling in a tight loop.
+A run takes minutes to hours: each agent may take up to 15 minutes per round, over several rounds. Start it in the background and wait for it to exit; it prints its log path at the start (`log/development.log` under the project unless `--log` says otherwise), which is what to read when the user asks how it is going. Avoid polling in a tight loop.
 
 When Redis answers, the run also serves the control room (it still ends at the fixed point, because of `--until-settled`) on `http://127.0.0.1:11000` and opens it in the browser: the user watches the board there and can message, interrupt or stop an agent. Without Redis the run warns once and goes on headless; that is not a failure. To get the page, start `redis-server` (or pass `--redis-url`) before the run; `openlanes-setup` has the details.
 
@@ -63,7 +63,7 @@ A warning about `ANTHROPIC_API_KEY` (or a similar variable) at the start means e
 When it exits, `openlanes status` shows where each plan stands. Sort them into three groups:
 
 - **Advanced to a human gate**: at ✅ Approved & Merged the reviewer has approved, and merging and deploying are the human's. Report the PR links (`gh pr list`).
-- **Blocked** ⭕️ / 🅱️: go to step 4.
+- **Blocked** ⭕ / 🛑: go to step 4.
 - **Unmoved without a block**: an agent failed or ran out of rounds. Read the plan's history with `openlanes state show --plan <NNN>` and say which agent stopped and why. Re-run with a fix (`--agent`, `--prompt`, `--timeout`) only after telling the user what you will change.
 
 ## 4. Unblock
@@ -71,7 +71,7 @@ When it exits, `openlanes status` shows where each plan stands. Sort them into t
 For each blocked plan:
 
 1. `openlanes unblock <NNN> -n` prints the open questions.
-1. Put them to the human **one at a time**. ⭕️ questions are for an engineer, 🅱️ for product; say which.
+1. Put them to the human **one at a time**. ⭕ questions are for an engineer, 🛑 for product; say which.
 1. Write each answer into the plan's `blocked.md` under `## A<n>`, matching its `## B<n>` (the format is in `openlanes-documents`). An answer counts only when it names who decided (a role is enough), carries today's date, and settles the question. "Leaning towards B" does not count, and the broker will leave it in place.
 
    ```markdown