maf 0.1.0

data/assets/doc-graph-refresh

@@ -0,0 +1,286 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# doc-graph-refresh - rebuild the knowledge graph after a markdown change.
+# Usage: .maf/bin/doc-graph-refresh post-commit|post-merge
+
+require "fileutils"
+require "tmpdir"
+require "time"
+
+abort "doc-graph-refresh: Ruby 3.0+ required (current: #{RUBY_VERSION})." if RUBY_VERSION.split(".").first.to_i < 3
+
+module DocGraph
+  # graphify names the output dir under --out "graphify-out". The graph lives
+  # in that dir at the project root, where graphify looks by default.
+  GRAPH = "graphify-out"
+  OBSIDIAN = File.join(GRAPH, "obsidian")
+  # The refresh never replaces these folders of the graph: memory/ holds the
+  # saved notes, obsidian/ holds the vault settings of the user.
+  KEPT = %w[memory obsidian].freeze
+  LOG = ".maf/coordination/doc-graph.log"
+  LOCK = ".maf/coordination/doc-graph.lock"
+  PENDING = ".maf/coordination/doc-graph.pending"
+  EVENTS = %w[post-commit post-merge].freeze
+  MARKDOWN = /\.md\z/i
+
+  # @param event [String] "post-commit" or "post-merge"
+  # @return [void]
+  def self.run(event)
+    return unless EVENTS.include?(event)
+
+    reason = skip_reason(event)
+    reason ? Log.write("#{event}: #{reason}") : refresh
+  end
+
+  def self.skip_reason(event)
+    return "no markdown change" unless markdown?(event)
+
+    "GEMINI_API_KEY unset, skipped" if ENV["GEMINI_API_KEY"].to_s.empty?
+  end
+
+  def self.markdown?(event)
+    Git.changed(event).any? { |file| file.match?(MARKDOWN) }
+  end
+
+  def self.refresh
+    return Lock.mark_pending unless Lock.acquire
+
+    run_locked([toplevel])
+    recheck
+  end
+
+  def self.run_locked(own)
+    drain(own)
+  ensure
+    Lock.release
+  end
+
+  def self.recheck
+    return unless Lock.pending? && Lock.acquire
+
+    run_locked([])
+    recheck
+  end
+
+  def self.drain(own)
+    trees = (own + Lock.take_pending).uniq
+    return if trees.empty?
+
+    trees.each { |tree| Refresh.run(tree) }
+    drain([])
+  end
+
+  def self.toplevel
+    path = Git.read("rev-parse", "--show-toplevel")
+    path.empty? ? Dir.pwd : path
+  end
+
+  def self.main
+    common = Git.read("rev-parse", "--git-common-dir")
+    common.empty? ? Dir.pwd : File.expand_path("..", common)
+  end
+
+  def self.graph_path = File.join(main, GRAPH)
+
+  module Git
+    def self.changed(event)
+      args = event == "post-merge" ? ["diff", "--name-only", "ORIG_HEAD", "HEAD"] : changed_commit
+      read(*args).lines.map(&:strip).reject(&:empty?)
+    end
+
+    def self.changed_commit
+      ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", "-m", "HEAD"]
+    end
+
+    def self.read(*args)
+      IO.popen(["git", *args], err: File::NULL, &:read).strip
+    rescue Errno::ENOENT
+      ""
+    end
+  end
+
+  module Lock
+    TTL = 3600
+
+    def self.acquire
+      FileUtils.mkdir_p(File.dirname(path(LOCK)))
+      take || (break_stale && take)
+    end
+
+    def self.take
+      Dir.mkdir(path(LOCK))
+      File.write(pid_file, Process.pid.to_s)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def self.break_stale
+      return false unless stale?
+
+      FileUtils.rm_rf(path(LOCK))
+      true
+    end
+
+    def self.stale?
+      holder = holder_pid
+      return holder_dead?(holder) if holder
+
+      Time.now - File.mtime(path(LOCK)) > TTL
+    rescue SystemCallError
+      false
+    end
+
+    def self.holder_dead?(pid)
+      Process.kill(0, pid) && Time.now - File.mtime(path(LOCK)) > TTL
+    rescue SystemCallError => e
+      e.is_a?(Errno::ESRCH)
+    end
+
+    def self.holder_pid
+      Integer(File.read(pid_file).strip)
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
+    def self.release
+      FileUtils.rm_rf(path(LOCK))
+    end
+
+    def self.mark_pending
+      FileUtils.mkdir_p(File.dirname(path(PENDING)))
+      File.open(path(PENDING), "a") { |io| io.puts(DocGraph.toplevel) }
+      Log.write("refresh already running; marked pending")
+    end
+
+    # The rename takes the list atomically. A new pending mark starts a new list.
+    def self.take_pending
+      taken = "#{path(PENDING)}.#{Process.pid}"
+      File.rename(path(PENDING), taken)
+      File.readlines(taken, chomp: true).reject(&:empty?).tap { FileUtils.rm_f(taken) }
+    rescue Errno::ENOENT
+      []
+    end
+
+    def self.pending? = File.exist?(path(PENDING))
+    def self.pid_file = File.join(path(LOCK), "pid")
+    def self.path(name) = File.join(DocGraph.main, name)
+  end
+
+  module Refresh
+    ATTEMPTS = 3
+    RETRY_WAIT = 30
+
+    def self.run(tree)
+      Dir.mktmpdir("doc-graph-refresh") { |tmp| seed_and_refresh(tmp, tree) }
+    rescue StandardError => e
+      Log.write("refresh failed: #{e.message}")
+    end
+
+    def self.seed_and_refresh(tmp, tree)
+      seed(tmp)
+      refresh(tmp, tree)
+    end
+
+    def self.seed(tmp)
+      graph = DocGraph.graph_path
+      return unless File.exist?(graph)
+
+      FileUtils.mkdir_p(File.join(tmp, GRAPH))
+      (Dir.children(graph) - KEPT).each { |name| FileUtils.cp_r(File.join(graph, name), File.join(tmp, GRAPH)) }
+    end
+
+    def self.refresh(tmp, tree)
+      return Log.write("extract failed; kept the old graph") unless build(tmp, tree)
+
+      Swap.move(File.join(tmp, GRAPH), DocGraph.graph_path)
+      Reflect.run
+      Export.run
+    end
+
+    def self.build(tmp, tree, attempt = 1)
+      return true if extract_ok?(tmp, tree)
+      return false if attempt >= ATTEMPTS
+
+      Log.write("extract attempt #{attempt} failed; retrying")
+      sleep(retry_wait)
+      build(tmp, tree, attempt + 1)
+    end
+
+    def self.retry_wait = Integer(ENV.fetch("DOC_GRAPH_RETRY_WAIT", RETRY_WAIT))
+
+    EXTRACT_FLAGS = %w[--backend gemini --max-concurrency 1].freeze
+
+    def self.extract_ok?(tmp, tree)
+      system({ "GRAPHIFY_OUT" => nil }, "graphify", "extract", tree, *EXTRACT_FLAGS, "--out", tmp) &&
+        File.exist?(File.join(tmp, GRAPH, "graph.json"))
+    end
+  end
+
+  # Swap replaces each derived entry of the graph folder on its own.
+  # The KEPT folders stay in place.
+  module Swap
+    def self.move(fresh, dest)
+      FileUtils.mkdir_p(dest)
+      (Dir.children(fresh) - KEPT).each { |name| replace(File.join(fresh, name), File.join(dest, name)) }
+    end
+
+    def self.replace(fresh, dest)
+      old = "#{dest}.old"
+      FileUtils.rm_rf(old)
+      FileUtils.mv(dest, old) if File.exist?(dest)
+      install(fresh, dest, old)
+    end
+
+    def self.install(fresh, dest, old)
+      FileUtils.mv(fresh, dest)
+      FileUtils.rm_rf(old)
+    rescue SystemCallError
+      FileUtils.mv(old, dest) if File.exist?(old)
+      raise
+    end
+  end
+
+  # Reflect rebuilds reflections/LESSONS.md from the saved notes in memory/.
+  # With the new graph, reflect drops each lesson node that the graph lost.
+  module Reflect
+    def self.run
+      graph = DocGraph.graph_path
+      return unless File.directory?(File.join(graph, "memory"))
+
+      system({ "GRAPHIFY_OUT" => nil }, "graphify", "reflect", "--graph", File.join(graph, "graph.json"),
+             "--memory-dir", File.join(graph, "memory"), "--out", File.join(graph, "reflections", "LESSONS.md"))
+    end
+  end
+
+  # Export writes the Obsidian vault to graphify-out/obsidian, the default
+  # folder of graphify. An agent that runs graphify export writes the same vault.
+  module Export
+    def self.run
+      graph_path = DocGraph.graph_path
+      command = ["graphify", "export", "obsidian", "--dir", OBSIDIAN]
+      Dir.chdir(DocGraph.main) { system({ "GRAPHIFY_OUT" => graph_path }, *command) }
+    end
+  end
+
+  module Log
+    def self.write(message)
+      File.open(path, "a") { |io| io.puts("#{Time.now.utc.iso8601} #{message}") }
+    rescue SystemCallError
+      nil
+    end
+
+    def self.path
+      path = File.join(DocGraph.main, DocGraph::LOG)
+      FileUtils.mkdir_p(File.dirname(path))
+      path
+    end
+  end
+end
+
+begin
+  DocGraph.run(ARGV.first)
+rescue StandardError => e
+  warn "doc-graph-refresh: #{e.message}"
+end

data/assets/env.sh

@@ -0,0 +1,6 @@
+# env.sh - shell environment of the multi-agent flow.
+# Usage: source .maf/env.sh
+# The file puts .maf/bin on PATH. After that, a worker runs `coord`, not `./coord`.
+MAF_BIN="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)/bin"
+export MAF_BIN
+case ":$PATH:" in *":$MAF_BIN:"*) ;; *) export PATH="$MAF_BIN:$PATH" ;; esac

data/assets/git-hooks/post-commit

@@ -0,0 +1,7 @@
+# >>> multi-agent-flow >>>
+# Doc-graph refresh: start it detached; the hook never fails a commit.
+_doc_graph_main=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." 2>/dev/null && pwd)
+if [ -n "$_doc_graph_main" ] && [ -x "$_doc_graph_main/.maf/bin/doc-graph-refresh" ]; then
+    nohup "$_doc_graph_main/.maf/bin/doc-graph-refresh" post-commit >/dev/null 2>&1 &
+fi
+# <<< multi-agent-flow <<<

data/assets/git-hooks/post-merge

@@ -0,0 +1,7 @@
+# >>> multi-agent-flow >>>
+# Doc-graph refresh: start it detached; the hook never fails a commit.
+_doc_graph_main=$(cd "$(git rev-parse --git-common-dir 2>/dev/null)/.." 2>/dev/null && pwd)
+if [ -n "$_doc_graph_main" ] && [ -x "$_doc_graph_main/.maf/bin/doc-graph-refresh" ]; then
+    nohup "$_doc_graph_main/.maf/bin/doc-graph-refresh" post-merge >/dev/null 2>&1 &
+fi
+# <<< multi-agent-flow <<<

data/assets/git-hooks/pre-commit

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# commit-guard - git pre-commit hook for the multi-agent flow.
+#
+# Refuses a commit when COORD_ROLE names a role with `can_edit: false` in
+# .maf/config.json (project manager, architect, reviewer). A role file tells
+# these roles not to edit code. This hook stops their edits from reaching a
+# branch. `git merge` does not run pre-commit, so the architect can still
+# merge task branches. A commit without COORD_ROLE (a human) always passes.
+require "json"
+
+module CommitGuard
+  MESSAGE = "commit-guard: role %s has can_edit false and cannot commit. " \
+            "Send the change to a worker role as a task."
+
+  # The main checkout holds the manifest. In a worktree, the common git dir
+  # is absolute. In the main checkout, it is relative to the checkout.
+  def self.root = File.dirname(File.expand_path(`git rev-parse --git-common-dir`.strip))
+
+  def self.agents
+    path = File.join(root, ".maf/config.json")
+    File.exist?(path) ? JSON.parse(File.read(path)).fetch("agents", []) : []
+  rescue JSON::ParserError
+    []
+  end
+
+  def self.read_only?(role) = agents.any? { |agent| agent["role"] == role && agent["can_edit"] == false }
+end
+
+role = ENV["COORD_ROLE"].to_s
+abort format(CommitGuard::MESSAGE, role) if !role.empty? && CommitGuard.read_only?(role)

data/assets/harness-hooks/board-watch-opencode.js

@@ -0,0 +1,87 @@
+// board-watch-opencode.js - opencode plugin that wakes an idle session when the board has work.
+//
+// opencode loads this file from .opencode/plugins/board-watch.js. When a
+// top-level session goes idle, the plugin checks the board at once and then
+// every BOARD_WATCH_INTERVAL seconds (default 60). Each check runs
+// .maf/coordination/harness-hooks/board-watch.rb --once. If the script exits 2,
+// the plugin sends the script output to the session as a new prompt. When a
+// session is busy again, the checks stop.
+//
+// board-watch.rb owns the board rules and the poke backoff.
+// Required env: COORD_ROLE (set by maf start). COORD_DIR and TASKRC optional.
+// The plugin does nothing if COORD_DISPATCHED is set: the dispatcher owns
+// the loop for dispatched agents.
+import { execFile } from "node:child_process"
+import path from "node:path"
+
+const WAKE = 2
+
+const server = async ({ client, directory }) => {
+  const role = process.env.COORD_ROLE || ""
+  if (!role || role === "unknown" || !process.env.MAF_SESSION_TOKEN || process.env.COORD_DISPATCHED) return {}
+
+  const script = path.join(directory, ".maf", "coordination", "harness-hooks", "board-watch.rb")
+  // Same rule as board-watch.rb: a whole number of seconds, else 60.
+  const raw = (process.env.BOARD_WATCH_INTERVAL || "").trim()
+  const interval = (/^\d+$/.test(raw) ? Number(raw) : 60) * 1000
+  let watched = null
+
+  const log = (message) =>
+    client.app.log({ body: { service: "board-watch", level: "error", message } }).catch(() => {})
+
+  // Returns the poke prompt, or null when the board has no work that is due.
+  // If ruby or the script fails, the plugin logs the error.
+  const check = (id, event = "Stop") =>
+    new Promise((resolve) => {
+      const child = execFile("ruby", [script, "--once"], { cwd: directory }, (error, stdout, stderr) => {
+        if (error && error.code !== WAKE) log(`${script} --once failed: ${stderr.trim() || error.message}`)
+        resolve(error?.code === WAKE ? stdout.trim() : null)
+      })
+      child.stdin.on("error", () => {})
+      child.stdin.end(JSON.stringify({ session_id: id, hook_event_name: event, cwd: directory }))
+    })
+
+  const stop = () => {
+    clearTimeout(watched?.timer)
+    watched = null
+  }
+
+  const poke = (id, text) =>
+    client.session
+      .promptAsync({ path: { id }, body: { agent: role, parts: [{ type: "text", text }] } })
+      .catch(() => {})
+
+  // Each watch gets a new entry. A check that ends after stop() or after a
+  // new watch sees a different entry and does nothing.
+  const tick = async (entry) => {
+    const prompt = await check(entry.id)
+    if (watched !== entry) return
+    if (!prompt) {
+      entry.timer = setTimeout(() => tick(entry), interval)
+      return
+    }
+    stop()
+    await poke(entry.id, prompt)
+  }
+
+  // A subagent session (for example explore) has a parent. Only the
+  // top-level session runs the work loop.
+  const watch = async (id) => {
+    const session = await client.session.get({ path: { id } }).catch(() => null)
+    if (!session?.data || session.data.parentID) return
+    await check(id, "SessionStart")
+    stop()
+    watched = { id, timer: null }
+    tick(watched)
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") return watch(event.properties.sessionID)
+      if (event.type === "session.status" && event.properties.status.type !== "idle") return stop()
+      if (event.type === "session.deleted" && event.properties.info?.id === watched?.id) return stop()
+    },
+  }
+}
+
+export default { id: "multi-agent-flow-board-watch", server }