maf 0.1.0 → 0.3.0

data/assets/coord

@@ -24,6 +24,7 @@ begin
   require_relative "../lib/maf/shared/roles"
   require_relative "../lib/maf/shared/git_exclude"
   require_relative "../lib/maf/shared/git_identity"
+  require_relative "../lib/maf/shared/harness"
 rescue LoadError
   abort "coord: the maf shared library is missing. Run maf update."
 end
@@ -53,6 +54,7 @@ module Coord
   # A claim older than this is presumed abandoned (crashed worker) and can be
   # taken over by `next`/`claim` without --force. Override with COORD_LEASE_TTL.
   DEFAULT_LEASE_TTL = 4 * 3600
+  BLOCKED_TAG = "blocked"
   DEFAULT_POLL_INTERVAL = 60
 
   # Lead roles plan and talk to the user. They never own a task, so they wait
@@ -85,6 +87,10 @@ module Coord
         coord conflicts                      list pending tasks with overlapping scopes
         coord claim ID [--force]             claim for COORD_WORKER (atomic; refused for lead roles)
         coord unclaim ID                     release a claim without finishing it
+        coord block ID [--kind K] TEXT...    release the claim, hold the task out of coord next, and tell
+                                             the architect (K=dependency) or the project manager
+                                             (K=needs_input, the default, capability, or failing)
+        coord unblock ID                     return a blocked task to the backlog
         coord done ID [--force]              complete (refused while the task branch lacks the goal head,
                                              or while the verify command fails)
         coord annotate ID TEXT...
@@ -119,7 +125,7 @@ module Coord
   COMMANDS = {
       "init" => :cmd_init, "add" => :cmd_add, "next" => :cmd_next,
       "conflicts" => :cmd_conflicts,
-      "claim" => :cmd_claim, "unclaim" => :cmd_unclaim,
+      "claim" => :cmd_claim, "unclaim" => :cmd_unclaim, "block" => :cmd_block, "unblock" => :cmd_unblock,
       "done" => :cmd_done, "annotate" => :cmd_annotate, "lesson" => :cmd_lesson,
     "msg" => :cmd_msg, "inbox" => :cmd_inbox, "await" => :cmd_await, "broadcast" => :cmd_broadcast,
     "log" => :cmd_log, "hooks" => :cmd_hooks,
@@ -200,7 +206,7 @@ module Coord
     def ensure_taskrc
       had_marker = File.exist?(@taskrc) && File.read(@taskrc).include?(MARKER)
       FileUtils.mkdir_p(File.dirname(@taskrc))
-      FileUtils.touch(@taskrc)
+      FileUtils.touch(@taskrc) unless File.exist?(@taskrc)
       ensure_data_location(warn_when_external: !had_marker)
       had_marker ? add_missing_udas : append_uda_block
     end
@@ -345,6 +351,9 @@ module Coord
     rescue ArgumentError
       false
     end
+
+    def self.blocked?(task) = Array(task["tags"]).include?(BLOCKED_TAG)
+    def self.held?(task) = waiting?(task) || blocked?(task)
   end
 
   # TaskCli runs Taskwarrior and parses its output. No domain logic here.
@@ -407,6 +416,8 @@ module Coord
       export([id, "export"]).first || {}
     end
 
+    def with_goal(uuid) = export(["goalid:#{uuid}", "export"])
+
     private
 
     def run(*args)
@@ -516,7 +527,7 @@ module Coord
     end
 
     def mine(role, worker)
-      pending.select { |task| task["role"] == role && task["worker"] == worker && task["start"] }
+      pending.select { |task| task["role"] == role && task["worker"] == worker && task["start"] && actionable?(task) }
     end
 
     # Returns the prior holder (nil if there was none) so the caller can warn
@@ -536,10 +547,18 @@ module Coord
       @cli.modify(id, "worker:")
     end
 
+    def block(id)
+      unclaim(id) if @cli.task(id)["start"]
+      @cli.modify(id, "+#{BLOCKED_TAG}")
+    end
+
+    def unblock(id) = @cli.modify(id, "-#{BLOCKED_TAG}")
+
     def find(id) = @cli.task(id)
     # A short id of digits only would read as a task number. The filter avoids that.
     def find_short(short) = @cli.task("uuid.startswith:#{short}")
     def for_goal(uuid) = pending.select { |task| task["goalid"] == uuid }
+    def any_for_goal?(uuid) = @cli.with_goal(uuid).any?
     def done(id) = @cli.done(id)
     def annotate(id, text) = @cli.annotate(id, text)
     def pending = @pending ||= @cli.pending
@@ -547,7 +566,7 @@ module Coord
 
     private
 
-    def actionable?(task) = !Schedule.waiting?(task)
+    def actionable?(task) = !Schedule.held?(task)
 
     def held_by?(task, worker) = !worker.to_s.empty? && task["worker"] == worker
 
@@ -840,20 +859,7 @@ module Coord
       entries.each { |entry| puts line(entry) }
     end
 
-    LEGACY_LIVE_WINDOW = 3600
-
-    def self.live_entry?(entry)
-      return false unless Maf::Shared::Processes.alive?(entry["pid"])
-
-      recorded = entry["started"].to_s
-      recorded.empty? ? legacy_live?(entry) : recorded == Maf::Shared::Processes.started_at(entry["pid"])
-    end
-
-    def self.legacy_live?(entry)
-      Time.now - Time.parse(entry["seen_at"].to_s) < LEGACY_LIVE_WINDOW
-    rescue ArgumentError
-      false
-    end
+    def self.live_entry?(entry) = Maf::Shared::Processes.live?(entry)
 
     private
 
@@ -1109,9 +1115,10 @@ end
 # Board renders status summaries and the Obsidian kanban file.
   class Board
     SECTIONS = {
-      "Backlog" => ->(task) { !Schedule.waiting?(task) && !task["start"] },
-      "In progress" => ->(task) { !Schedule.waiting?(task) && task["start"] },
-      "Waiting" => ->(task) { Schedule.waiting?(task) }
+      "Backlog" => ->(task) { !Schedule.held?(task) && !task["start"] },
+      "In progress" => ->(task) { !Schedule.held?(task) && task["start"] },
+      "Waiting" => ->(task) { Schedule.waiting?(task) && !Schedule.blocked?(task) },
+      "Blocked" => ->(task) { Schedule.blocked?(task) }
     }.freeze
 
     def initialize(tasks, paths)
@@ -1161,6 +1168,7 @@ end
     end
 
     def bucket(task)
+      return "blocked" if Schedule.blocked?(task)
       return "waiting" if Schedule.waiting?(task)
 
       task["start"] ? "in-progress" : "backlog"
@@ -1197,6 +1205,8 @@ end
     def self.run(dir, *args) = system("git", "-C", dir, *args, out: File::NULL, err: File::NULL)
     def self.branch?(dir, name) = run(dir, "show-ref", "--verify", "--quiet", "refs/heads/#{name}")
     def self.clean?(dir) = `git -C #{Shellwords.escape(dir)} status --porcelain --untracked-files=no`.strip.empty?
+    def self.changed(dir) = out(dir, "diff", "HEAD", "--name-only").lines(chomp: true)
+    def self.remote_branch?(dir, remote, name) = run(dir, "ls-remote", "--exit-code", "--heads", remote, name)
     def self.out(dir, *args) = IO.popen(["git", "-C", dir, *args], err: File::NULL, &:read).strip
     def self.ancestor?(dir, older, newer) = run(dir, "merge-base", "--is-ancestor", older, newer)
     def self.own_commits?(dir, base, branch) = out(dir, "rev-list", "--count", "#{base}..#{branch}").to_i.positive?
@@ -1257,11 +1267,12 @@ end
       goals.each { |goal| puts goal_line(goal) }
     end
 
-    def show(id)
+    def show(id, artifacts_dir)
       goal = find!(id)
       puts goal_line(goal)
       list = @tasks.for_goal(goal["uuid"])
       list.empty? ? puts("  no open tasks") : list.each { |task| puts task_line(task) }
+      plan_hint(goal["uuid"], artifacts_dir)
     end
 
     def done(id)
@@ -1278,6 +1289,13 @@ end
 
     private
 
+    def plan_hint(uuid, artifacts_dir)
+      plan = File.join(artifacts_dir, uuid, "plan.md")
+      return unless File.exist?(plan) && !@tasks.any_for_goal?(uuid)
+
+      puts "  plan ready, no tasks: #{plan}. The plan waits for approval."
+    end
+
     def goal_line(goal)
       open = @tasks.for_goal(goal["uuid"]).size
       [goal["uuid"], goal["description"], self.class.branch(goal["uuid"]), "open=#{open}"].join("\t")
@@ -1298,7 +1316,7 @@ end
     end
 
     def start(uuid, base)
-      raise Error, "uncommitted changes in #{@dir}. Commit or stash them first." unless Git.clean?(@dir)
+      refuse_dirty!
 
       branch = "task/#{Goals.short(uuid)}"
       raise Error, "git checkout #{branch} failed" unless checkout(branch, base)
@@ -1308,6 +1326,17 @@ end
 
     private
 
+    FLOW_FILES = "These are files of the flow, and git tracks them. In the main checkout, run maf untrack and commit."
+
+    def refuse_dirty!
+      paths = Git.changed(@dir)
+      return if paths.empty?
+
+      flow = paths.all? { |path| path.start_with?(".maf/") || Worktree::RUNTIME_FILES.include?(path) }
+      raise Error, ["uncommitted changes in #{@dir}: #{paths.first(5).join(", ")}#{" ..." if paths.size > 5}.",
+                    flow ? FLOW_FILES : "Commit or stash them first."].join(" ")
+    end
+
     def checkout(branch, base)
       return Git.run(@dir, "checkout", "-q", branch) if Git.branch?(@dir, branch)
 
@@ -1363,8 +1392,8 @@ end
   # commit. The task branch is then deleted. A worker worktree that still has
   # the task branch checked out moves back to its worker branch first.
   class Land
-    def initialize(root, task)
-      @root, @task = root, task
+    def initialize(root, task, base)
+      @root, @task, @base = root, task, base
     end
 
     def run(subject)
@@ -1393,8 +1422,14 @@ end
       return nil unless Git.own_commits?(@root, goal_branch, branch)
       raise Error, STALE % { branch: branch, goal: goal_branch } unless Git.ancestor?(@root, goal_branch, branch)
 
+      parent = base_parent
       merge_squash
-      commit(SquashMessage.for(@task, subject))
+      commit(SquashMessage.for(@task, subject), parent)
+    end
+
+    def base_parent
+      held = Git.out(@root, "merge-base", Git.base_ref(@root, @base), branch)
+      held unless held.empty? || Git.ancestor?(@root, held, goal_branch)
     end
 
     STALE = "branch %<branch>s lacks the head of %<goal>s. Open a fix task: merge %<goal>s into %<branch>s."
@@ -1407,14 +1442,30 @@ end
     end
 
     # coord makes this commit, not the role, so the commit guard does not apply.
-    def commit(message)
-      return nil if Git.run(goal_dir, "diff", "--cached", "--quiet")
+    def commit(message, parent)
+      return nil if Git.run(goal_dir, "diff", "--cached", "--quiet") && parent.nil?
 
+      parent ? merge_commit(message, parent) : squash_commit(message)
+      Git.out(goal_dir, "rev-parse", "--short", "HEAD")
+    end
+
+    def squash_commit(message)
       args = ["git", "-C", goal_dir, "commit", "-q", "--no-verify", "-F", "-"]
       IO.popen(args, "w") { |io| io.write(message) }
       raise Error, "git commit on #{goal_branch} failed" unless $?.success?
+    end
 
-      Git.out(goal_dir, "rev-parse", "--short", "HEAD")
+    def merge_commit(message, parent)
+      head = Git.out(goal_dir, "rev-parse", "HEAD")
+      sha = commit_tree(message, head, parent)
+      moved = sha && Git.run(goal_dir, "update-ref", "HEAD", sha, head)
+      raise Error, "git commit on #{goal_branch} failed" unless moved
+    end
+
+    def commit_tree(message, *parents)
+      args = ["commit-tree", Git.out(goal_dir, "write-tree"), *parents.flat_map { |sha| ["-p", sha] }, "-F", "-"]
+      sha, status = Open3.capture2("git", "-C", goal_dir, *args, stdin_data: message)
+      sha.strip if status.success?
     end
 
     def release_branch
@@ -1660,6 +1711,18 @@ end
       raise Error, "git push of #{branch} to #{remote} failed"
     end
 
+    def push_with_base(branch, base)
+      push_missing(base)
+      push(branch)
+    end
+
+    def push_missing(branch)
+      return if !Git.branch?(@root, branch) || Git.remote_branch?(@root, remote, branch)
+
+      push(branch)
+      puts "pushed #{branch}: #{remote} had no branch #{branch}"
+    end
+
     def create_pr(head:, base:, title:, body:)
       args = ["--head", head, "--base", base, "--title", title, "--reviewer", reviewer, "--body-file", "-"]
       gh("pr", "create", "--repo", repo, *args, input: body).lines.last.to_s.strip
@@ -1823,11 +1886,17 @@ end
     def write(dir, slug)
       slot = Slots.new(@coord_dir).assign(slug)
       FileUtils.mkdir_p(File.join(dir, MAF_DIR))
-      File.write(File.join(dir, FILE), base_lines(slot) + hook_lines(dir, slot))
+      save(File.join(dir, FILE), base_lines(slot) + hook_lines(dir, slot))
     end
 
     private
 
+    def save(file, text)
+      File.write(file, text) unless File.exist?(file) && File.read(file) == text
+    rescue SystemCallError => e
+      warn "coord: cannot write #{file} (#{e.message}). Run coord worktree outside the sandbox to update it."
+    end
+
     def base_lines(slot)
       "export COORD_DIR=#{@coord_dir}\nexport TASKRC=#{File.join(@coord_dir, "taskrc")}\n" \
         "export COORD_SLOT=#{slot}\n#{bin_lines}"
@@ -1913,10 +1982,11 @@ end
     # slash, so it also matches the symlink.
     GRAPH_DIR = "graphify-out"
     LOCAL_EXCLUDES = [ENV_FILE, "/#{GRAPH_DIR}"].freeze
-    RUNTIME_FILES = %w[.maf/bin/coord .maf/coordination/harness-hooks/next-task.rb
-                       .maf/coordination/harness-hooks/board-watch.rb .maf/coordination/harness-hooks/session-guard.rb
-                       .maf/coordination/harness-hooks/context-watch.rb .codex/hooks.json
-                       .opencode/plugins/board-watch.js].freeze
+    # The hook files of the flow, and the files that each harness writes in a worktree.
+    RUNTIME_FILES = (%w[.maf/bin/coord .maf/coordination/harness-hooks/next-task.rb
+                        .maf/coordination/harness-hooks/board-watch.rb .maf/coordination/harness-hooks/session-guard.rb
+                        .maf/coordination/harness-hooks/context-watch.rb] +
+                     Maf::Shared::Harness.all.flat_map(&:runtime_files)).freeze
 
     def self.dir_for(root, slug) = Maf::Shared::Project.worktree_dir(root, slug)
 
@@ -2025,6 +2095,14 @@ end
 
       FileUtils.mkdir_p(File.dirname(dest))
       FileUtils.cp(src, dest, preserve: true)
+    rescue Errno::EPERM, Errno::EROFS => e
+      blocked(src, e)
+    end
+
+    def blocked(src, error)
+      raise error unless src.start_with?(File.join(@root, MAF_DIR, ""))
+
+      abort "coord: cannot copy #{src} into the worktree in the sandbox. Run coord worktree on the host."
     end
 
     # The graph is not committed. A relative symlink gives the worktree the
@@ -2083,7 +2161,10 @@ end
     def timeout = (v = value_of("--timeout")) && v.to_i
 
     def require_arg(command, name)
-      shift || abort("usage: coord #{command} #{name}")
+      value = shift
+      abort("usage: coord #{command} #{name}") if value.nil? || value.start_with?("-")
+
+      value
     end
 
     def require_text(command)
@@ -2241,6 +2322,42 @@ end
     end
   end
 
+  # Block commands hold a task out of coord next, tell the role that can
+  # remove the blocker, and return the task.
+  module BlockCommands
+    BLOCK_KINDS = %w[needs_input dependency capability failing].freeze
+    BLOCK_USAGE = "usage: coord block ID [--kind #{BLOCK_KINDS.join("|")}] TEXT...".freeze
+
+    def cmd_block
+      kind = block_kind(@args.value_of("--kind") || BLOCK_KINDS.first)
+      id = @args.require_arg("block", "ID")
+      block(id, kind, @args.require_text("block"))
+      puts "blocked #{id} (#{kind})"
+    end
+
+    def block(id, kind, text)
+      tasks.annotate(id, "BLOCKED (#{kind}): #{text}")
+      tasks.block(id)
+      event_log.append("block", @worker, "#{id} #{kind} #{text}")
+      notify_block(id, kind, text)
+    end
+
+    def block_kind(kind) = BLOCK_KINDS.include?(kind) ? kind : abort(BLOCK_USAGE)
+
+    def notify_block(id, kind, text)
+      return deliver("architect", @role, "BLOCKED task #{id} (dependency), #{@worker}: #{text}") if kind == "dependency"
+
+      send_escalation(id, "blocked (#{kind}): #{text}")
+    end
+
+    def cmd_unblock
+      id = @args.require_arg("unblock", "ID")
+      tasks.unblock(id)
+      event_log.append("unblock", @worker, id)
+      puts "unblocked #{id}"
+    end
+  end
+
   # Claim commands take, release, note, and finish a task.
   module ClaimCommands
     def cmd_claim
@@ -2454,8 +2571,9 @@ end
       event_log.append("broadcast", @worker, text)
     end
 
-    NO_PUSH = "coord: %<role>s has no live session and no message hook. The message waits until a %<role>s " \
-              "session starts. Fix: maf start HARNESS %<role>s --dispatch --detach, " \
+    NO_PUSH = "coord: %<role>s has no live session and no message hook. " \
+              "The message waits until a session of %<role>s starts. " \
+              "Fix: maf start HARNESS %<role>s --dispatch --detach, " \
               "or add an executable .maf/coordination/message-hooks/%<role>s.sh"
 
     # A message is pushed by a hook or read by a live session. Without both,
@@ -2564,7 +2682,7 @@ end
     def cmd_land
       subject = @args.value_of("--subject")
       task = find_task!(@args.require_arg("land", "ID"))
-      land = Land.new(main_root, task)
+      land = Land.new(main_root, task, Git.base_branch(main_root, manifest))
       commit = locks.with_mutex("land-#{Goals.short(task["goalid"])}", worker: @worker) { land.run(subject) }
       record_landing(task, commit, land)
     end
@@ -2587,7 +2705,7 @@ end
       setup.ensure_taskrc
       goals.find!(id)["uuid"]
     end
-    def goal_show = goals.show(@args.require_arg("goal show", "ID"))
+    def goal_show = goals.show(@args.require_arg("goal show", "ID"), File.join(paths.coord_dir, "artifacts"))
 
     def goal_sync
       goal = goals.find!(@args.require_arg("goal sync", "ID"))
@@ -2617,11 +2735,18 @@ end
       raise Error, "base branch #{base} does not exist" unless Git.branch?(main_root, base)
 
       uuid = tasks.add(title: opts[:title], role: Goals::ROLE, ref: opts[:ref])
-      Worktree.new(main_root).checkout(Goals.slug(uuid), Goals.branch(uuid), base)
+      open_goal_branch(uuid, base)
       event_log.append("goal", @worker, opts[:title])
       puts uuid
     end
 
+    def open_goal_branch(uuid, base)
+      Worktree.new(main_root).checkout(Goals.slug(uuid), Goals.branch(uuid), base)
+      return if !Git.run(main_root, "remote", "get-url", "origin") || Git.remote_branch?(main_root, "origin", base)
+
+      warn "coord: origin has no branch #{base}. coord goal pr pushes the local #{base} again."
+    end
+
     UNSYNCED = "coord: %<branch>s lacks the head of %<ref>s. Run coord goal sync %<id>s. " \
                "Run the merge suite again. Then run coord goal done again."
 
@@ -2715,7 +2840,7 @@ end
 
     def publish_goal(goal, entry)
       branch = Goals.branch(goal["uuid"])
-      github.push(branch)
+      github.push_with_base(branch, Git.base_branch(main_root, manifest))
       push_memory
       entry = entry ? update_pr(goal, entry, branch) : { "url" => open_pr(goal, branch), "seen" => [] }
       review_state.put(goal["uuid"], entry.merge("head" => Git.out(main_root, "rev-parse", branch)))
@@ -2802,6 +2927,7 @@ end
     def cmd_worktree
       role = @args.require_arg("worktree", "ROLE")
       worker = @args.shift
+      abort "usage: coord worktree ROLE [WORKER]" if worker&.start_with?("-")
       warn_missing_role_files(role)
       Worktree.new(@project_root).create(role, worker)
     end
@@ -2897,6 +3023,7 @@ end
   class CLI
     include TaskCommands
     include ClaimCommands
+    include BlockCommands
     include MessageCommands
     include InboxCommands
     include GoalCommands

data/assets/dashboard

@@ -137,11 +137,7 @@ end
       {}
     end
 
-    # A pid can belong to a new process. The recorded start time tells them apart.
-    def live?(presence)
-      pid = presence["pid"].to_i
-      Maf::Shared::Processes.alive?(pid) && [nil, "", Maf::Shared::Processes.started_at(pid)].include?(presence["started"])
-    end
+    def live?(presence) = Maf::Shared::Processes.live?(presence)
 
     def tail(name)
       path = File.join(sessions, name)