repos/OWNER/REPO/issues/41/comments

```

## Prerequisites

An issue can wait on other issues in the same repository.

| Operation | Method | Path |

|---|---|---|

| Read the graph | `GET` | `repos/OWNER/REPO/issues/NUMBER/dependencies` |

| Record prerequisites | `POST` | `repos/OWNER/REPO/issues/NUMBER/dependencies` |

| Remove one | `DELETE` | `repos/OWNER/REPO/issues/NUMBER/dependencies/BLOCKER_NUMBER` |

Record that issue 42 waits on issues 9 and 12:

```sh

printf '%s' '{"blocked_by":[9,12]}' | \

  openagents api -X POST --input - \

  repos/OWNER/REPO/issues/42/dependencies

```

Pick up work that nothing blocks:

```sh

openagents api "repos/OWNER/REPO/issues?state=open&blocked=false"

```

Every issue response also carries `openagents.blocked`, `openagents.blocked_by`,

and `openagents.blocks`. `blocked` is derived from the prerequisites' state, so

closing the last open prerequisite unblocks the issue with no second write. An

unknown number, a self reference, and an edge that would close a cycle each

return `422`, and none of the batch is recorded.

## Projects

There are no named `project` commands. Construct every Projects V2 route manually under `repos/OWNER/REPO/projectsV2`.

  alias OpenAgents.Accounts.User

  alias OpenAgents.Analytics

  alias OpenAgents.Issues.{Comment, Issue}

  alias OpenAgents.Issues.{Comment, Issue, IssueDependency}

  alias OpenAgents.Labels

  alias OpenAgents.Labels.Label

  alias OpenAgents.Milestones

  One page of the filtered issue list, with the unpaginated total.

  Supported options: `:state`, `:label`, `:assignee`, `:milestone`, `:q`,

  and `:page`. Filters compose; counts and pages always agree because they

  read the same query.

  `:blocked`, and `:page`. Filters compose; counts and pages always agree

  because they read the same query.

  """

  def list_issues_page(%Repository{} = repository, opts) when is_list(opts) do

    page = max(parse_page(opts[:page]), 1)

    |> maybe_filter_assignee(Keyword.get(opts, :assignee))

    |> maybe_filter_milestone(Keyword.get(opts, :milestone))

    |> maybe_filter_search(Keyword.get(opts, :q))

    |> maybe_filter_blocked(Keyword.get(opts, :blocked))

  end

  def get_issue!(%Repository{id: repository_id}, id) do

    update_issue(issue, %{"assignees" => assignees})

  end

  @doc """

  The prerequisite edges touching `issues`, keyed by issue id.

  One query serves a whole page, so rendering a list never walks the graph once

  per row. Each entry carries what the issue waits on, what waits on it, and

  whether any prerequisite is still open.

  """

  def dependency_graph(issues) when is_list(issues) do

    ids = Enum.map(issues, & &1.id)

    base = Map.new(ids, &{&1, %{blocked_by: [], blocks: []}})

    from(dependency in IssueDependency,

      join: blocked in Issue,

      on: blocked.id == dependency.issue_id,

      join: blocker in Issue,

      on: blocker.id == dependency.blocked_by_issue_id,

      where: dependency.issue_id in ^ids or dependency.blocked_by_issue_id in ^ids,

      select: %{

        blocked_id: blocked.id,

        blocker_id: blocker.id,

        blocked_summary: %{number: blocked.number, title: blocked.title, state: blocked.state},

        blocker_summary: %{number: blocker.number, title: blocker.title, state: blocker.state}

      }

    )

    |> Repo.all()

    |> Enum.reduce(base, fn edge, graph ->

      graph

      |> collect_edge(edge.blocked_id, :blocked_by, edge.blocker_summary)

      |> collect_edge(edge.blocker_id, :blocks, edge.blocked_summary)

    end)

    |> Map.new(fn {id, entry} -> {id, derive_blocked(entry)} end)

  end

  @doc "The prerequisite edges of one issue, in the shape `dependency_graph/1` returns."

  def dependencies(%Issue{} = issue), do: [issue] |> dependency_graph() |> Map.fetch!(issue.id)

  defp collect_edge(graph, issue_id, key, summary) do

    case Map.fetch(graph, issue_id) do

      {:ok, entry} -> Map.put(graph, issue_id, Map.update!(entry, key, &[summary | &1]))

      :error -> graph

    end

  end

  # An issue is blocked while a prerequisite is still open, so the flag is read

  # from the prerequisites already loaded rather than stored on the issue.

  defp derive_blocked(%{blocked_by: blocked_by, blocks: blocks}) do

    blocked_by = Enum.sort_by(blocked_by, & &1.number)

    %{

      blocked_by: blocked_by,

      blocks: Enum.sort_by(blocks, & &1.number),

      blocked: Enum.any?(blocked_by, &(&1.state == "open"))

    }

  end

  @doc """

  Records the issues numbered `numbers` as prerequisites of `issue`.

  All of them or none: the numbers are validated and inserted in one

  transaction, so a request naming one unknown issue records nothing. Adding a

  prerequisite that is already recorded succeeds without a second row.

  Returns `:ok`, or `{:error, reason}` where reason is

  `{:invalid_number, value}`, `{:self_reference, number}`,

  `{:missing_issue, number}`, or `{:cycle, numbers}`. The cycle numbers name

  the path the edge would close, starting and ending at `issue`.

  """

  def add_dependencies(%Issue{} = issue, numbers, actor \\ nil)

      when is_list(numbers) and (is_nil(actor) or is_struct(actor, User)) do

    Repo.transaction(fn ->

      Enum.each(numbers, fn number ->

        case add_dependency(issue, number, actor) do

          :ok -> :ok

          {:error, reason} -> Repo.rollback(reason)

        end

      end)

    end)

    |> case do

      {:ok, _result} ->

        Repositories.broadcast_issues(issue.repository_id)

        :ok

      {:error, reason} ->

        {:error, reason}

    end

  end

  defp add_dependency(issue, number, actor) do

    with {:ok, number} <- normalize_issue_number(number),

         :ok <- reject_self_reference(issue, number),

         {:ok, blocker} <- fetch_blocker(issue, number),

         :ok <- reject_cycle(issue, blocker) do

      insert_dependency(issue, blocker, actor)

    end

  end

  defp normalize_issue_number(number) when is_integer(number) and number > 0, do: {:ok, number}

  defp normalize_issue_number(number) when is_binary(number) do

    case Integer.parse(number) do

      {parsed, ""} -> normalize_issue_number(parsed)

      _other -> {:error, {:invalid_number, number}}

    end

  end

  defp normalize_issue_number(number), do: {:error, {:invalid_number, number}}

  defp reject_self_reference(%Issue{number: number}, number),

    do: {:error, {:self_reference, number}}

  defp reject_self_reference(_issue, _number), do: :ok

  defp fetch_blocker(issue, number) do

    case Repo.get_by(Issue, repository_id: issue.repository_id, number: number) do

      %Issue{} = blocker -> {:ok, blocker}

      nil -> {:error, {:missing_issue, number}}

    end

  end

  # The new edge closes a cycle exactly when the prerequisite already waits on

  # the issue it would block. A backlog whose graph can contain a cycle cannot

  # be scheduled, so the walk runs before the insert rather than at read time.

  defp reject_cycle(issue, blocker) do

    case dependency_path(blocker.id, issue.id) do

      nil -> :ok

      path -> {:error, {:cycle, [issue.number | issue_numbers(path)]}}

    end

  end

  defp dependency_path(from_id, target_id),

    do: walk_dependencies([[from_id]], MapSet.new([from_id]), target_id)

  defp walk_dependencies([], _visited, _target_id), do: nil

  defp walk_dependencies([path | queue], visited, target_id) do

    next_ids = blocker_ids(hd(path))

    if target_id in next_ids do

      Enum.reverse([target_id | path])

    else

      unvisited = Enum.reject(next_ids, &MapSet.member?(visited, &1))

      walk_dependencies(

        queue ++ Enum.map(unvisited, &[&1 | path]),

        Enum.into(unvisited, visited),

        target_id

      )

    end

  end

  defp blocker_ids(issue_id) do

    Repo.all(

      from dependency in IssueDependency,

        where: dependency.issue_id == ^issue_id,

        select: dependency.blocked_by_issue_id

    )

  end

  defp issue_numbers(ids) do

    numbers =

      from(issue in Issue, where: issue.id in ^ids, select: {issue.id, issue.number})

      |> Repo.all()

      |> Map.new()

    Enum.flat_map(ids, fn id ->

      case Map.fetch(numbers, id) do

        {:ok, number} -> [number]

        :error -> []

      end

    end)

  end

  defp insert_dependency(issue, blocker, actor) do

    %IssueDependency{}

    |> IssueDependency.changeset(%{

      "repository_id" => issue.repository_id,

      "issue_id" => issue.id,

      "blocked_by_issue_id" => blocker.id,

      "created_by_user_id" => actor && actor.id

    })

    |> Repo.insert(on_conflict: :nothing, conflict_target: [:issue_id, :blocked_by_issue_id])

    |> case do

      {:ok, _dependency} -> :ok

      {:error, changeset} -> {:error, {:invalid_dependency, changeset}}

    end

  end

  @doc """

  Removes the prerequisite numbered `number` from `issue`.

  Returns `{:error, {:missing_dependency, number}}` when the edge is not

  recorded, because a silent no-op hides the mismatch from the caller.

  """

  def remove_dependency(%Issue{} = issue, number) do

    with {:ok, number} <- normalize_issue_number(number),

         {:ok, blocker} <- fetch_blocker(issue, number) do

      from(dependency in IssueDependency,

        where: dependency.issue_id == ^issue.id and dependency.blocked_by_issue_id == ^blocker.id

      )

      |> Repo.delete_all()

      |> case do

        {0, _returned} ->

          {:error, {:missing_dependency, number}}

        {_count, _returned} ->

          Repositories.broadcast_issues(issue.repository_id)

          :ok

      end

    end

  end

  def set_milestone(%Issue{} = issue, nil) do

    update_issue(issue, %{"milestone" => nil})

  end

    )

  end

  # Blocked is a property of the prerequisite's current state, so the filter

  # asks the graph rather than a column: an issue is blocked while any issue it

  # is blocked by is still open. Closing the last prerequisite moves the issue

  # into `blocked=false` with no second write.

  defp maybe_filter_blocked(query, nil), do: query

  defp maybe_filter_blocked(query, true),

    do: where(query, [], exists(open_blocker_query()))

  defp maybe_filter_blocked(query, false),

    do: where(query, [], not exists(open_blocker_query()))

  defp open_blocker_query do

    from dependency in IssueDependency,

      join: blocker in Issue,

      on: blocker.id == dependency.blocked_by_issue_id,

      where: dependency.issue_id == parent_as(:issue).id and blocker.state == "open",

      select: 1

  end

  defp maybe_filter_search(query, nil), do: query

  defp maybe_filter_search(query, ""), do: query

defmodule OpenAgents.Issues.IssueDependency do

  @moduledoc """

  One prerequisite edge: `issue` cannot start until `blocked_by_issue` closes.

  The edge is the whole record. Whether an issue is blocked is never stored,

  because a stored flag goes stale the moment a prerequisite closes. Read it

  from the prerequisite's own state instead.

  """

  use Ecto.Schema

  import Ecto.Changeset

  alias OpenAgents.Accounts.User

  alias OpenAgents.Issues.Issue

  alias OpenAgents.Repositories.Repository

  @primary_key {:id, :binary_id, autogenerate: true}

  schema "issue_dependencies" do

    belongs_to :repository, Repository, type: :binary_id

    belongs_to :issue, Issue

    belongs_to :blocked_by_issue, Issue

    belongs_to :created_by_user, User, type: :binary_id

    timestamps(type: :utc_datetime)

  end

  @doc false

  def changeset(dependency, attrs) do

    dependency

    |> cast(attrs, [:repository_id, :issue_id, :blocked_by_issue_id, :created_by_user_id])

    |> validate_required([:repository_id, :issue_id, :blocked_by_issue_id])

    |> check_constraint(:blocked_by_issue_id,

      name: :issue_dependencies_no_self_reference,

      message: "cannot depend on itself"

    )

    |> unique_constraint([:issue_id, :blocked_by_issue_id])

    |> foreign_key_constraint(:repository_id)

    |> foreign_key_constraint(:issue_id)

    |> foreign_key_constraint(:blocked_by_issue_id)

  end

end

      "get /api/v3/repos/:owner/:repo/milestones/:milestone_number" => :anonymous,

      "get /api/v3/repos/:owner/:repo/assignees" => :anonymous,

      "get /api/v3/repos/:owner/:repo/assignees/:assignee" => :anonymous,

      # Anonymous by design: the extension index is a public API description.

      "get /api/v3" => :anonymous,

      # Anonymous by design: device authorization bootstraps credentials.

      "post /api/v3/device/authorizations" => :anonymous,

      "post /api/v3/device/authorizations/token" => :anonymous,

      "get /api/v3/repos/:owner/:repo" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/issues" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/issues/:issue_number" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/pulls" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/pulls/:pull_number" => :optional_bearer,

      "get /api/v3/repos/:owner/:repo/projectsV2" => :optional_bearer,

      "get /api/v3/forum/claims" => :required_bearer,

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/assignees" => :required_bearer,

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/comments" => :required_bearer,

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies" => :required_bearer,

      "delete /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies/:blocked_by_number" =>

        :required_bearer,

      "post /api/v3/repos/:owner/:repo/issues/:issue_number/labels" => :required_bearer,

      "post /api/v3/repos/:owner/:repo/labels" => :required_bearer,

      "post /api/v3/repos/:owner/:repo/milestones" => :required_bearer,

defmodule OpenAgentsWeb.ApiExtensionController do

  @moduledoc """

  The index of OpenAgents extension fields this deployment serves.

  A field is expected to be read only after it appears here, so an agent can

  discover the OpenAgents-specific parts of the API mechanically instead of

  reading prose. Responses that carry an extension also name it in the

  `x-openagents-extensions` response header.

  """

  use OpenAgentsWeb, :controller

  @issue_reference %{

    "type" => "object",

    "properties" => %{

      "number" => %{"type" => "integer"},

      "title" => %{"type" => "string"},

      "state" => %{"type" => "string", "enum" => ["open", "closed"]}

    }

  }

  @extensions %{

    "issue.openagents" => %{

      "version" => "2026-08-23",

      "description" => "OpenAgents-specific issue fields, namespaced away from the GitHub shape.",

      "fields" => %{

        "blocked" => %{

          "type" => "boolean",

          "description" => "True while any issue in blocked_by is still open."

        },

        "blocked_by" => %{

          "type" => "array",

          "items" => @issue_reference,

          "description" => "Issues that must close before this issue can start."

        },

        "blocks" => %{

          "type" => "array",

          "items" => @issue_reference,

          "description" => "Issues that wait on this issue."

        }

      },

      "filters" => %{

        "blocked" => %{

          "endpoint" => "GET /api/v3/repos/{owner}/{repo}/issues",

          "type" => "boolean",

          "description" => "Lists issues that do or do not have an open prerequisite."

        }

      },

      "endpoints" => [

        "GET /api/v3/repos/{owner}/{repo}/issues/{issue_number}/dependencies",

        "POST /api/v3/repos/{owner}/{repo}/issues/{issue_number}/dependencies",

        "DELETE /api/v3/repos/{owner}/{repo}/issues/{issue_number}/dependencies/{blocked_by_number}"

      ]

    }

  }

  def show(conn, _params) do

    json(conn, %{"api_version" => "v3", "extensions" => @extensions})

  end

end

    with :ok <- validate_index_params(params),

         {issues, total} <-

           Issues.list_issues_page(repository, index_options(params)) do

      render(conn, :index,

      conn

      |> put_extensions_header()

      |> render(:index,

        issues: issues,

        owner: owner,

        repo: repo,

        dependencies: Issues.dependency_graph(issues),

        pagination: %{

          page: Issues.parse_page(params["page"]),

          per_page: Issues.per_page(),

      Map.has_key?(params, "page") and not valid_page?(params["page"]) ->

        {:error, :page, "must be a positive integer"}

      Map.has_key?(params, "blocked") and blocked_filter(params["blocked"]) == :invalid ->

        {:error, :blocked, "must be true or false"}

      true ->

        :ok

    end

      assignee: params["assignee"],

      milestone: params["milestone"],

      q: params["q"],

      blocked: blocked_filter(params["blocked"]),

      page: params["page"]

    ]

  end

  # An agent asking "what can I start right now?" sends `blocked=false`. The

  # answer is derived from prerequisite state, so no value other than the two

  # booleans has a meaning to guess at.

  defp blocked_filter(nil), do: nil

  defp blocked_filter("true"), do: true

  defp blocked_filter("false"), do: false

  defp blocked_filter(true), do: true

  defp blocked_filter(false), do: false

  defp blocked_filter(_value), do: :invalid

  def create(conn, %{"owner" => owner, "repo" => repo} = params) do

    repository = Repositories.get_writable_by_path!(owner, repo, conn.assigns.current_user)

      {:ok, %Issue{} = issue} ->

        conn

        |> put_status(:created)

        |> render(:show, issue: issue, owner: owner, repo: repo)

        |> put_extensions_header()

        |> render(:show,

          issue: issue,

          owner: owner,

          repo: repo,

          dependencies: dependencies(issue)

        )

      {:error, %Ecto.Changeset{} = changeset} ->

        conn

        OpenAgentsWeb.ControllerHelpers.integer_param!(issue_number)

      )

    render(conn, :show, issue: issue, owner: owner, repo: repo)

    conn

    |> put_extensions_header()

    |> render(:show, issue: issue, owner: owner, repo: repo, dependencies: dependencies(issue))

  rescue

    Ecto.NoResultsError ->

      conn

    case Issues.update_issue(issue, params, conn.assigns.current_user) do

      {:ok, %Issue{} = issue} ->

        render(conn, :show, issue: issue, owner: owner, repo: repo)

        conn

        |> put_extensions_header()

        |> render(:show,

          issue: issue,

          owner: owner,

          repo: repo,

          dependencies: dependencies(issue)

        )

      {:error, %Ecto.Changeset{} = changeset} ->

        conn

      |> json(%{message: "Not Found"})

  end

  defp dependencies(%Issue{} = issue), do: Issues.dependency_graph([issue])

  # The extension namespace is discoverable from the response itself, so a

  # client never has to infer which OpenAgents fields this deployment sends.

  defp put_extensions_header(conn),

    do: put_resp_header(conn, "x-openagents-extensions", "issue.openagents")

  defp not_found(conn) do

    conn |> put_status(:not_found) |> json(%{message: "Not Found"})

  end

defmodule OpenAgentsWeb.IssueDependencyController do

  @moduledoc """

  Prerequisite edges between the issues of one repository.

  The response is the same object the issue extension carries, so a client that

  reads `issue.openagents` and a client that reads this endpoint agree without

  translating between two shapes.

  """

  use OpenAgentsWeb, :controller

  alias OpenAgents.Issues

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.ControllerHelpers

  def index(conn, %{"owner" => owner, "repo" => repo, "issue_number" => issue_number}) do

    repository = Repositories.get_visible_by_path!(owner, repo, conn.assigns[:current_user])

    issue =

      Issues.get_issue_by_number!(repository, ControllerHelpers.integer_param!(issue_number))

    json(conn, Issues.dependencies(issue))

  rescue

    Ecto.NoResultsError -> not_found(conn)

  end

  def create(

        conn,

        %{"owner" => owner, "repo" => repo, "issue_number" => issue_number} = params

      ) do

    repository = Repositories.get_writable_by_path!(owner, repo, conn.assigns.current_user)

    issue =

      Issues.get_issue_by_number!(repository, ControllerHelpers.integer_param!(issue_number))

    case params["blocked_by"] do

      numbers when is_list(numbers) ->

        add_dependencies(conn, issue, numbers)

      _other ->

        unprocessable(conn, "must be a list of issue numbers in this repository")

    end

  rescue

    Ecto.NoResultsError -> not_found(conn)

  end

  def delete(conn, %{

        "owner" => owner,

        "repo" => repo,

        "issue_number" => issue_number,

        "blocked_by_number" => blocked_by_number

      }) do

    repository = Repositories.get_writable_by_path!(owner, repo, conn.assigns.current_user)

    issue =

      Issues.get_issue_by_number!(repository, ControllerHelpers.integer_param!(issue_number))

    case Issues.remove_dependency(issue, blocked_by_number) do

      :ok ->

        json(conn, Issues.dependencies(issue))

      {:error, {:missing_dependency, number}} ->

        message(conn, :not_found, "Issue ##{number} is not a prerequisite of this issue")

      {:error, {:missing_issue, number}} ->

        message(conn, :not_found, "Issue ##{number} does not exist in this repository")

      {:error, {:invalid_number, _value}} ->

        not_found(conn)

    end

  rescue

    Ecto.NoResultsError -> not_found(conn)

  end

  defp add_dependencies(conn, issue, numbers) do

    case Issues.add_dependencies(issue, numbers, conn.assigns.current_user) do

      :ok ->

        conn |> put_status(:created) |> json(Issues.dependencies(issue))

      {:error, reason} ->

        unprocessable(conn, error_message(reason))

    end

  end

  defp error_message({:invalid_number, value}),

    do: "#{inspect(value)} is not an issue number"

  defp error_message({:self_reference, number}),

    do: "Issue ##{number} cannot be a prerequisite of itself"

  defp error_message({:missing_issue, number}),

    do: "Issue ##{number} does not exist in this repository"

  defp error_message({:cycle, numbers}),

    do: "Would create a dependency cycle: #{Enum.map_join(numbers, " -> ", &"##{&1}")}"

  defp error_message({:invalid_dependency, changeset}) do

    changeset

    |> Ecto.Changeset.traverse_errors(fn {message, _options} -> message end)

    |> Enum.map_join("; ", fn {field, messages} ->

      "#{field} #{Enum.join(messages, ", ")}"

    end)

  end

  defp unprocessable(conn, message) do

    conn

    |> put_status(:unprocessable_entity)

    |> json(%{errors: %{blocked_by: [message]}})

  end

  defp message(conn, status, message) do

    conn |> put_status(status) |> json(%{message: message})

  end

  defp not_found(conn), do: message(conn, :not_found, "Not Found")

end

defmodule OpenAgentsWeb.IssueJSON do

  @moduledoc """

  Renders GitHub-compatible issue JSON.

  GitHub-shaped keys keep their exact shape. OpenAgents-specific fields live

  under one `openagents` object, so a GitHub client sees an additional object

  and nothing else. The object appears only when the caller supplies the

  `:dependencies` graph, because an absent graph is not the same fact as an

  issue with no prerequisites.

  """

  def render("index.json", %{issues: issues, pagination: pagination} = assigns) do

      html_url: "#{url_base}/#{owner}/#{repo}/issues/#{issue.number}",

      url: "#{url_base}/api/v3/repos/#{owner}/#{repo}/issues/#{issue.number}"

    }

    |> put_extension(issue, assigns)

  end

  defp put_extension(json, issue, assigns) do

    case Map.get(assigns, :dependencies) do

      nil -> json

      graph -> Map.put(json, :openagents, extension_json(graph, issue))

    end

  end

  defp extension_json(graph, issue) do

    dependencies = Map.get(graph, issue.id, %{blocked: false, blocked_by: [], blocks: []})

    %{

      blocked: dependencies.blocked,

      blocked_by: dependencies.blocked_by,

      blocks: dependencies.blocks

    }

  end

  defp total_pages(0, _per_page), do: 1

  @optional_forge_read_paths [

    "/api/v3/repos/:owner/:repo/issues",

    "/api/v3/repos/:owner/:repo/issues/:issue_number",

    "/api/v3/repos/:owner/:repo/issues/:issue_number/dependencies",

    "/api/v3/repos/:owner/:repo/pulls",

    "/api/v3/repos/:owner/:repo/pulls/:pull_number",

    "/api/v3/repos/:owner/:repo/projectsV2",

       when verb in [:get, :head],

       do: declaration(:public_read, "anonymous", "published:api-contract", false)

  defp policy(%{path: "/api/v3", verb: verb}) when verb in [:get, :head],

    do: declaration(:public_read, "anonymous", "published:api-extensions", false)

  defp policy(%{path: "/controller/pairings", verb: :post}),

    do: declaration(:machine, "unpaired machine", "machine:pairing:create", true)

  scope "/api/v3", OpenAgentsWeb do

    pipe_through :api

    get "/", ApiExtensionController, :show

    post "/device/authorizations", DeviceAuthorizationController, :create

    post "/device/authorizations/token", DeviceAuthorizationController, :token

    get "/repos/:owner/:repo", RepositoryController, :show

    get "/repos/:owner/:repo/issues", IssueController, :index

    get "/repos/:owner/:repo/issues/:issue_number", IssueController, :show

    get "/repos/:owner/:repo/issues/:issue_number/dependencies",

        IssueDependencyController,

        :index

    get "/repos/:owner/:repo/pulls", PullRequestController, :index

    get "/repos/:owner/:repo/pulls/:pull_number", PullRequestController, :show

    get "/repos/:owner/:repo/projectsV2", ProjectController, :index

    put "/repos/:owner/:repo/issues/comments/:id", CommentController, :update

    patch "/repos/:owner/:repo/issues/comments/:id", CommentController, :update

    delete "/repos/:owner/:repo/issues/comments/:id", CommentController, :delete

    post "/repos/:owner/:repo/issues/:issue_number/dependencies",

         IssueDependencyController,

         :create

    delete "/repos/:owner/:repo/issues/:issue_number/dependencies/:blocked_by_number",

           IssueDependencyController,

           :delete

    post "/repos/:owner/:repo/issues/:issue_number/labels", IssueLabelController, :create

    delete "/repos/:owner/:repo/issues/:issue_number/labels/:name", IssueLabelController, :delete

    post "/repos/:owner/:repo/issues/:issue_number/assignees", IssueAssigneeController, :create

List responses use named envelopes. For example, the issue list returns an

object with an `issues` array.

## Issue prerequisites

An issue can wait on other issues in the same repository.

```text

GET    /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies

POST   /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies

DELETE /api/v3/repos/:owner/:repo/issues/:issue_number/dependencies/:blocked_by_number

```

`POST` takes the issue numbers this issue waits on and returns the resulting

graph:

```json

{ "blocked_by": [9, 12] }

```

```json

{

  "blocked": true,

  "blocked_by": [{ "number": 9, "title": "Deliver the work system", "state": "open" }],

  "blocks": []

}

```

Every issue response carries the same object under `openagents`, and a response

that carries it names the namespace in the `x-openagents-extensions` header.

`GET /api/v3` lists the extension fields this deployment serves.

`blocked` is derived from the prerequisites' own state, so closing the last open

prerequisite unblocks the issue with no second write. The issue list filters on

it, which answers "what can an agent start right now":

```text

GET /api/v3/repos/:owner/:repo/issues?blocked=false

GET /api/v3/repos/:owner/:repo/issues?blocked=true

```

Prerequisites stay inside one repository. An unknown number, a self reference,

and an edge that would close a cycle each return `422 Unprocessable Entity`,

and none of the batch is recorded. Reading the graph needs the same access as

reading the issue. Recording or removing an edge needs repository write access.

## Labels

```text

    20260823010819,

    20260823013135,

    20260823021021,

    20260823034851

    20260823034851,

    20260823040635

  ],

  "required_tables": [

    "users",

defmodule OpenAgents.Repo.Migrations.CreateIssueDependencies do

  use Ecto.Migration

  def change do

    create table(:issue_dependencies, primary_key: false) do

      add :id, :binary_id, primary_key: true

      add :repository_id, references(:repositories, type: :binary_id, on_delete: :delete_all),

        null: false

      add :issue_id, references(:issues, on_delete: :delete_all), null: false

      add :blocked_by_issue_id, references(:issues, on_delete: :delete_all), null: false

      add :created_by_user_id, references(:users, type: :binary_id, on_delete: :nilify_all)

      timestamps(type: :utc_datetime)

    end

    # One edge per ordered pair, so recording the same prerequisite twice is a

    # no-op rather than a duplicate the graph has to deduplicate on every read.

    create unique_index(:issue_dependencies, [:issue_id, :blocked_by_issue_id])

    # Both directions are read equally often: an issue asks what blocks it, and

    # a closing issue asks what it releases.

    create index(:issue_dependencies, [:blocked_by_issue_id])

    create index(:issue_dependencies, [:repository_id])

    create constraint(:issue_dependencies, :issue_dependencies_no_self_reference,

             check: "issue_id <> blocked_by_issue_id"

           )

  end

end

defmodule OpenAgents.IssueDependenciesTest do

  use OpenAgents.DataCase

  alias OpenAgents.Issues

  setup do

    {:ok, repository: repository_fixture()}

  end

  describe "add_dependencies/3" do

    test "records a prerequisite in both directions", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Aim agents at the backlog"})

      {:ok, blocker} = Issues.create_issue(repository, %{title: "Deliver the work system"})

      assert :ok = Issues.add_dependencies(blocked, [blocker.number])

      assert %{blocked: true, blocked_by: [%{number: blocker_number, state: "open"}], blocks: []} =

               Issues.dependencies(blocked)

      assert blocker_number == blocker.number

      assert %{blocked: false, blocked_by: [], blocks: [%{number: blocked_number}]} =

               Issues.dependencies(blocker)

      assert blocked_number == blocked.number

    end

    test "recording the same prerequisite twice leaves one edge", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Second"})

      {:ok, blocker} = Issues.create_issue(repository, %{title: "First"})

      assert :ok = Issues.add_dependencies(blocked, [blocker.number])

      assert :ok = Issues.add_dependencies(blocked, [blocker.number])

      assert %{blocked_by: [_one]} = Issues.dependencies(blocked)

    end

    test "one unknown number records none of the batch", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Blocked"})

      {:ok, blocker} = Issues.create_issue(repository, %{title: "Blocker"})

      assert {:error, {:missing_issue, 4_242}} =

               Issues.add_dependencies(blocked, [blocker.number, 4_242])

      assert %{blocked: false, blocked_by: []} = Issues.dependencies(blocked)

    end

    test "an issue in another repository is not a prerequisite here", %{repository: repository} do

      other_repository = repository_fixture()

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Local"})

      {:ok, _first} = Issues.create_issue(other_repository, %{title: "First elsewhere"})

      {:ok, elsewhere} = Issues.create_issue(other_repository, %{title: "Elsewhere"})

      refute elsewhere.number == blocked.number

      assert {:error, {:missing_issue, number}} =

               Issues.add_dependencies(blocked, [elsewhere.number])

      assert number == elsewhere.number

    end

    test "an issue cannot be its own prerequisite", %{repository: repository} do

      {:ok, issue} = Issues.create_issue(repository, %{title: "Alone"})

      assert {:error, {:self_reference, number}} =

               Issues.add_dependencies(issue, [issue.number])

      assert number == issue.number

    end

    test "a value that is not an issue number is refused", %{repository: repository} do

      {:ok, issue} = Issues.create_issue(repository, %{title: "Alone"})

      assert {:error, {:invalid_number, "soon"}} = Issues.add_dependencies(issue, ["soon"])

    end

    test "an edge that would close a cycle is refused", %{repository: repository} do

      {:ok, first} = Issues.create_issue(repository, %{title: "First"})

      {:ok, second} = Issues.create_issue(repository, %{title: "Second"})

      {:ok, third} = Issues.create_issue(repository, %{title: "Third"})

      assert :ok = Issues.add_dependencies(second, [first.number])

      assert :ok = Issues.add_dependencies(third, [second.number])

      assert {:error, {:cycle, path}} = Issues.add_dependencies(first, [third.number])

      assert path == [first.number, third.number, second.number, first.number]

      assert %{blocked_by: []} = Issues.dependencies(first)

    end

  end

  describe "derived blocked state" do

    test "closing the last prerequisite unblocks the issue", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Waiting"})

      {:ok, blocker} = Issues.create_issue(repository, %{title: "Prerequisite"})

      assert :ok = Issues.add_dependencies(blocked, [blocker.number])

      assert %{blocked: true} = Issues.dependencies(blocked)

      {:ok, blocker} = Issues.update_issue(blocker, %{"state" => "closed"})

      assert %{blocked: false, blocked_by: [%{state: "closed"}]} = Issues.dependencies(blocked)

      {:ok, _reopened} = Issues.update_issue(blocker, %{"state" => "open"})

      assert %{blocked: true} = Issues.dependencies(blocked)

    end

    test "one open prerequisite among closed ones still blocks", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Waiting"})

      {:ok, done} = Issues.create_issue(repository, %{title: "Done", state: "closed"})

      {:ok, pending} = Issues.create_issue(repository, %{title: "Pending"})

      assert :ok = Issues.add_dependencies(blocked, [done.number, pending.number])

      assert %{blocked: true, blocked_by: [_first, _second]} = Issues.dependencies(blocked)

    end

  end

  describe "remove_dependency/2" do

    test "removes one edge and leaves the rest", %{repository: repository} do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Waiting"})

      {:ok, first} = Issues.create_issue(repository, %{title: "First"})

      {:ok, second} = Issues.create_issue(repository, %{title: "Second"})

      assert :ok = Issues.add_dependencies(blocked, [first.number, second.number])

      assert :ok = Issues.remove_dependency(blocked, first.number)

      assert %{blocked_by: [%{number: remaining}]} = Issues.dependencies(blocked)

      assert remaining == second.number

    end

    test "removing an edge that is not recorded reports the mismatch", %{

      repository: repository

    } do

      {:ok, blocked} = Issues.create_issue(repository, %{title: "Waiting"})

      {:ok, other} = Issues.create_issue(repository, %{title: "Unrelated"})

      assert {:error, {:missing_dependency, number}} =

               Issues.remove_dependency(blocked, other.number)

      assert number == other.number

    end