trace.issue

One issue with the branches that name it — local, and remote-tracking where only the remote still has the branch — and, for each, the commits it holds that the trunk did not: measured against the trunk while the branch is open, and against the first parent of the merge commit that brought it in once it is merged. A branch that reached the trunk without a merge commit of its own says so and claims nothing, because its commits cannot be told from the trunk's. The milestone comes from the canonical issue record, which is the one edge here that git does not hold, and `declared` says whether the project model has this id at all — a repository with no plan still gets the branches, and a typo still cannot read as work nobody did.

query
behaviorally_verified
module trace
#trace
#git
#plan
#issue
#provenance

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_trace_issue
HTTP	GET /api/v1/trace/issue operationId trace.issue
command line	—

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · TraceIssueInput

One issue of the project model.

property	type	required	description
issue	string	yes	The issue id, as the project model spells it (`I1305`). An id the model does not declare is answered with `declared: false` rather than refused, and rather than answered with a bare empty trace: a typo that read as "nothing realised this issue" is the one answer this capability must never give.

JSON Schema

{
  "additionalProperties": false,
  "description": "One issue of the project model.",
  "properties": {
    "issue": {
      "description": "The issue id, as the project model spells it (`I1305`). An id the model does not\ndeclare is answered with `declared: false` rather than refused, and rather than\nanswered with a bare empty trace: a typo that read as \"nothing realised this issue\"\nis the one answer this capability must never give.",
      "type": "string"
    }
  },
  "required": [
    "issue"
  ],
  "title": "TraceIssueInput",
  "type": "object"
}

output · IssueTrace

Everything git knows about one issue's realisation.

property	type	required	description
branches	array	yes	The branches that name it, local first.
commits	integer	yes	How many distinct commits the branches hold between them.
complete	boolean	yes	True when every branch's commits could be derived. False when at least one reached the trunk without a merge commit, so part of the work is not distinguishable.
declared	boolean	yes	True when the project model declares this id. False is not an error and not an empty answer: it says the id was looked for and the model does not have it, which a caller must be able to tell apart from "declared, and nothing has realised it yet". A repository with no project model at all answers `false` for every id rather than refusing, because the branches naming an id are still derivable there.
issue	string	yes	The issue id, as the project model spells it.
milestone	string \| null	no	The milestone the canonical issue record names. Git does not hold this edge and nothing here derives it: the caller with the index fills it in, and it is `null` in a repository whose issue record does not name one.
trunk	string \| null	no	The trunk every branch was measured against.

JSON Schema

{
  "$defs": {
    "BranchTrace": {
      "description": "One branch that names an issue, with the commits it holds.",
      "properties": {
        "commits": {
          "description": "The commits this branch holds and the trunk did not, newest first, merges excluded.",
          "items": {
            "$ref": "#/$defs/CommitRef"
          },
          "type": "array"
        },
        "head": {
          "description": "The commit the ref points at.",
          "type": "string"
        },
        "integration": {
          "$ref": "#/$defs/Integration",
          "description": "How it stands to the trunk."
        },
        "merge_commit": {
          "description": "The merge commit that brought it into the trunk, when one did.",
          "type": [
            "string",
            "null"
          ]
        },
        "name": {
          "description": "The ref, short: `feature/I1305-traceability`, or `origin/feature/I1305-traceability`\nwhen only the remote still has it.",
          "type": "string"
        },
        "note": {
          "description": "Why the commit list is what it is, when it is worth a sentence.",
          "type": [
            "string",
            "null"
          ]
        },
        "remote": {
          "description": "True when the ref is a remote-tracking one and no local branch of the same name\nstands for it.",
          "type": "boolean"
        }
      },
      "required": [
        "name",
        "remote",
        "head",
        "integration",
        "commits"
      ],
      "type": "object"
    },
    "CommitRef": {
      "description": "One commit, exactly as git names it. Nothing here is stored anywhere: the whole record\nis re-read from the object database on every call.",
      "properties": {
        "author": {
          "description": "The author, as the commit records them.",
          "type": "string"
        },
        "date": {
          "description": "The author date, ISO 8601 as the commit records it.",
          "type": "string"
        },
        "id": {
          "description": "The full object name.",
          "type": "string"
        },
        "short": {
          "description": "The abbreviated object name, as this repository abbreviates it.",
          "type": "string"
        },
        "subject": {
          "description": "The subject line.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "short",
        "author",
        "date",
        "subject"
      ],
      "type": "object"
    },
    "Integration": {
      "description": "How a branch stands to the trunk, which is what decides which commits are its own.",
      "oneOf": [
        {
          "const": "open",
          "description": "Not reachable from the trunk: its commits are the ones the trunk does not have.",
          "type": "string"
        },
        {
          "const": "merged",
          "description": "Reachable from the trunk through a merge commit, which the trace names: its commits\nare the ones that merge brought in.",
          "type": "string"
        },
        {
          "const": "absorbed",
          "description": "Reachable from the trunk with no merge commit of its own — fast-forwarded, or\nrebased onto it. Its commits cannot be told from the trunk's and none are claimed.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "The trunk is unknown, so there is nothing to measure the branch against.",
          "type": "string"
        }
      ]
    }
  },
  "description": "Everything git knows about one issue's realisation.",
  "properties": {
    "branches": {
      "description": "The branches that name it, local first.",
      "items": {
        "$ref": "#/$defs/BranchTrace"
      },
      "type": "array"
    },
    "commits": {
      "description": "How many distinct commits the branches hold between them.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "complete": {
      "description": "True when every branch's commits could be derived. False when at least one reached\nthe trunk without a merge commit, so part of the work is not distinguishable.",
      "type": "boolean"
    },
    "declared": {
      "description": "True when the project model declares this id. False is not an error and not an\nempty answer: it says the id was looked for and the model does not have it, which a\ncaller must be able to tell apart from \"declared, and nothing has realised it yet\".\nA repository with no project model at all answers `false` for every id rather than\nrefusing, because the branches naming an id are still derivable there.",
      "type": "boolean"
    },
    "issue": {
      "description": "The issue id, as the project model spells it.",
      "type": "string"
    },
    "milestone": {
      "description": "The milestone the canonical issue record names. Git does not hold this edge and\nnothing here derives it: the caller with the index fills it in, and it is `null` in\na repository whose issue record does not name one.",
      "type": [
        "string",
        "null"
      ]
    },
    "trunk": {
      "description": "The trunk every branch was measured against.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "issue",
    "declared",
    "branches",
    "commits",
    "complete"
  ],
  "title": "IssueTrace",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: disabled — every call runs the handler

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	1	first-issue
mcp	covered	1	first-issue
http	covered	1	first-issue