HTTP API: trace

Which branches and commits realised an issue, and which issue and milestone a commit served — derived from git and from the canonical project model on every call, stored nowhere. A branch names an issue when one of its path components is an issue id; a commit belongs to the issue whose branches hold it; a commit no such branch holds is reported as unattributed rather than left out, because work with no execution contract is what a traceability report exists to make visible. Pull requests are a GitHub fact and this executable makes no network call: `scripts/traceability` reads them and joins them to this answer over the branch name.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

trace

GET /api/v1/trace trace.report

The whole work graph above the branch

Every issue at least one branch names with its branches and commits, every declared issue no branch names, and the newest stretch of the trunk with each commit attributed to the issue whose branches hold it or reported as unattributed. The tallies count both sides, so the proportion of the trunk that no execution contract accounts for is a number rather than an impression. Read from git on every call: the history changes outside this process.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_traceability
MCP resource {"name": "traceability", "uri": "majordomus://traceability"}

Query parameters

name	type	required	description	examples
limit	integer (uint)	no	How many trunk commits to attribute, newest first. Default: 50. Anything above 2000 is read as 2000 — a traceability report is a reading, not a history export.	ten: 10

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/trace?limit=10"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	TraceReport	The whole work graph above the branch: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/trace/commit trace.commit

What contract this commit served

One commit with the issue and milestone it served, or the fact that none can be found. Attributed when exactly one issue's branches hold it, ambiguous when branches naming two issues do, and unattributed when no branch naming an issue holds it at all — which is either work committed without an execution contract or a branch deleted after its merge, and the answer says so rather than guessing between them.

query
behaviorally_verified
benchmark required
cache disabled
MCP tool majordomus_trace_commit

Query parameters

name	type	required	description	examples
commit	string	yes	Anything git resolves to a commit: a full or abbreviated object name, a ref, `HEAD`, `master~3`.	head: "HEAD"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/trace/commit?commit=HEAD"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	CommitAttribution	What contract this commit served: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/trace/issue trace.issue

What realised this 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
benchmark required
cache disabled
MCP tool majordomus_trace_issue

Query parameters

name	type	required	description	examples
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.	first-issue: "I0001"

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/trace/issue?issue=I0001"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	IssueTrace	What realised this issue: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

Attribution

"attributed" | "unattributed" | "ambiguous"

What is known about the contract one commit served.

attributedExactly one issue's branches contain it.
unattributedNo branch naming an issue contains it.
ambiguousBranches naming more than one issue contain it.

Used by CommitAttribution

BranchTrace

object

One branch that names an issue, with the commits it holds.

property	type	required	description
name	string	yes	The ref, short: `feature/I1305-traceability`, or `origin/feature/I1305-traceability` when only the remote still has it.
remote	boolean	yes	True when the ref is a remote-tracking one and no local branch of the same name stands for it.
head	string	yes	The commit the ref points at.
integration	Integration → Integration	yes	How it stands to the trunk.
merge_commit	string \| null	no	The merge commit that brought it into the trunk, when one did.
note	string \| null	no	Why the commit list is what it is, when it is worth a sentence.
commits	array of CommitRef → CommitRef	yes	The commits this branch holds and the trunk did not, newest first, merges excluded.

Used by IssueTrace

CommitAttribution

object

One commit and the contract it served, or the fact that none can be found.

property	type	required	description
commit	CommitRef → CommitRef	yes	The commit.
attribution	Attribution → Attribution	yes	What is known.
issue	string \| null	no	The issue, when exactly one claims it.
milestone	string \| null	no	The milestone that issue belongs to, filled by the caller that has the index.
issues	array of string	yes	Every issue whose branches contain it: one when attributed, none when unattributed, more than one when ambiguous.
branches	array of string	yes	The branches that contain it, by the names their refs carry.
reason	string	yes	Why the verdict is what it is, in one line a person can act on.

Used by trace.commit TraceReport

CommitRef

object

One commit, exactly as git names it. Nothing here is stored anywhere: the whole record is re-read from the object database on every call.

property	type	required	description
id	string	yes	The full object name.
short	string	yes	The abbreviated object name, as this repository abbreviates it.
author	string	yes	The author, as the commit records them.
date	string	yes	The author date, ISO 8601 as the commit records it.
subject	string	yes	The subject line.

Used by BranchTrace CommitAttribution

Integration

"open" | "merged" | "absorbed" | "unknown"

How a branch stands to the trunk, which is what decides which commits are its own.

openNot reachable from the trunk: its commits are the ones the trunk does not have.
mergedReachable from the trunk through a merge commit, which the trace names: its commits are the ones that merge brought in.
absorbedReachable from the trunk with no merge commit of its own — fast-forwarded, or rebased onto it. Its commits cannot be told from the trunk's and none are claimed.
unknownThe trunk is unknown, so there is nothing to measure the branch against.

Used by BranchTrace

IssueTrace

object

Everything git knows about one issue's realisation.

property	type	required	description
issue	string	yes	The issue id, as the project model spells it.
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.
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.
branches	array of BranchTrace → BranchTrace	yes	The branches that name it, local first.
commits	integer (uint)	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.

Used by trace.issue TraceReport

TraceReport

object

The whole traceability answer: every issue git can say something about, and every commit of a stretch of the trunk with the contract it served or the fact that it has none.

property	type	required	description
trunk	string \| null	no	The trunk every branch and commit was measured against.
examined	integer (uint)	yes	How many trunk commits were attributed.
issues	array of IssueTrace → IssueTrace	yes	The issues that at least one branch names, in id order.
without_branch	array of string	yes	The issue ids the project model declares that no ref names. Not a fault: an issue nobody has started has no branch yet.
commits	array of CommitAttribution → CommitAttribution	yes	The examined trunk commits, newest first.
tallies	TraceTallies → TraceTallies	yes	The counts, so a caller need not add them up.

Used by trace.report

TraceTallies

object

The counts of one report.

property	type	required	description
issues_declared	integer (uint)	yes	Issue ids the project model declares.
issues_with_branch	integer (uint)	yes	Of those, the ones at least one ref names.
branches	integer (uint)	yes	Branches naming an issue.
branch_commits	integer (uint)	yes	Distinct commits those branches claim.
attributed	integer (uint)	yes	Examined trunk commits with exactly one issue.
unattributed	integer (uint)	yes	Examined trunk commits no branch naming an issue contains.
ambiguous	integer (uint)	yes	Examined trunk commits more than one issue claims.

Used by TraceReport