Skip to content

Milestones and issues as data; status derived, never stored

An issue records what happened to it and the engine derives whether it is blocked, ready, active, verifying or done from the dependency graph, so the roadmap cannot disagree with the plan.

status
feature status: stable

What it does

majordomus plan validate refuses a cycle, an edge that resolves to nothing and a record that breaks its schema; plan next answers which issues may be executed now; plan roadmap draws the milestone graph the website renders. A branch created for an issue is named after it, so the worktree topology can read the issue back from the branch, and an issue is done only with the evidence its contract requires. Above the branch the same edge is read in both directions and stored nowhere: the trace capability module derives an issue's branches and commits from git, scripts/traceability joins the pull requests GitHub holds, and a commit no execution contract accounts for is reported as unattributed rather than quietly left out.

Above the milestones, an intent states what must become true and the evidence that settles it. majordomus intent derives its stage from the plan and each criterion from the evidence ledger, answers which intent the work on an issue serves when a worker asks, refuses a criterion no issue serves and work that started before its plan was critiqued, and joins the work realising it across sessions and providers; the Cockpit shows the same answers at /cockpit/intents.

What it does not do

It does not talk to GitHub on its own: the projection of issues and milestones is rendered offline and applied only when a person runs the sync with a token. Nothing here estimates effort or schedules dates. An intent is enforced when work starts only where the policy requires binding (intent.binding: required); elsewhere it is judged after the fact. The GitHub projection closes a milestone without reading the intents it realises.

Why it exists

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

Traceability trace behaviorally verified

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.

The plan and its derivations plan behaviorally verified

The milestone and issue model of this repository, and everything derived from it that nobody authored: the status of each record, the dependency graphs above and below the milestone boundary, the topological execution waves, the roadmap order, the milestone being executed and the one issue to take next. Status is never stored — a record says what happened to it and the status follows from that and from the state of its dependencies — so no file can contradict the graph. This capability reads; writing a lifecycle marker into a record is `plan.transition`, which declares that it writes the repository.

Executable development scopes devtask behaviorally verified

An issue and a milestone read as work to be done rather than as metadata: what a person authored, where the plan graph puts it, what happened to it locally, where its external projection stands, and whether a worker may start it — with the origin of every value on the value. Nothing here is a second project model: the records are the canonical ones, the status and the graph are `plan`'s, the branches and commits are `trace`'s, the readiness vocabulary refines three canonical statuses without replacing any, and the projection onto GitHub stays `scripts/github-sync`'s. Nothing here writes anything, which is what makes a user-authored GitHub value safe from it.

Intent intents behaviorally verified

What must become true above the milestones that realise it: each intent's statement, invariants and satisfaction criteria, its stage derived from the plan's milestone status, each criterion's state derived from the evidence ledger, and its verdict derived from those criteria alone. Nothing is stored and nothing transitions; an intent added under the project model is answered by all of these without a registration anywhere.

Intent realization intent_realization behaviorally verified

Which work realises which intent: every task of this checkout's ledger with the episodes, providers and handovers that carried it, every closed session record and every claim on the peer board, joined through the plan to the intents they serve, each link marked declared, observed, derived or inferred; each intent's unmet criteria with the issues serving them; and the drift between closed work and current evidence. Derived on every read and stored nowhere, so an intent outlives every session and provider that worked on it.

The objects it is made of

Kinds of the layer. Each is a schema, a source class and a file on disk; the number beside it is what this repository holds today, counted at build time.

  • milestone111
  • issue1027
  • intent43
  • gap5
  • critique37

Where it sits

domain
Coordination — Every worker declares the paths it will touch, sees who else is working and where, and hears about a collision before it is committed.
areas of work
work-tracking

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

The capabilities behind this feature, by interface
capabilitycommand lineHTTPMCP tool
trace.commit —none GET /api/v1/trace/commit majordomus_trace_commit
trace.issue —none GET /api/v1/trace/issue majordomus_trace_issue
trace.report —none GET /api/v1/trace majordomus_traceability
plan.delivery majordomus plan delivery GET /api/v1/plan/delivery majordomus_plan_delivery
plan.drift majordomus plan drift GET /api/v1/plan/drift majordomus_plan_drift
plan.flight —none GET /api/v1/plan/flight majordomus_plan_flight
plan.issues —none GET /api/v1/plan/issues majordomus_plan_issues
plan.model —none GET /api/v1/plan majordomus_plan
plan.next —none GET /api/v1/plan/next majordomus_plan_next
plan.record —none GET /api/v1/plan/record majordomus_plan_record
plan.roadmap —none GET /api/v1/plan/roadmap majordomus_plan_roadmap
plan.status —none GET /api/v1/plan/status majordomus_plan_status
plan.transition —none POST /api/v1/plan/transition majordomus_plan_transition
plan.validate —none GET /api/v1/plan/validate majordomus_plan_validate
plan.waves —none GET /api/v1/plan/waves majordomus_plan_waves
devtask.issue majordomus devtask issue GET /api/v1/devtask/issue majordomus_devtask
devtask.milestone majordomus devtask milestone GET /api/v1/devtask/milestone majordomus_devtask_milestone
intents.binding majordomus intent binding GET /api/v1/intents/binding majordomus_intent_binding
intents.coverage majordomus intent coverage GET /api/v1/intents/coverage majordomus_intent_coverage
intents.list majordomus intent list GET /api/v1/intents majordomus_intents
intents.preflight majordomus intent preflight GET /api/v1/intents/preflight majordomus_intent_preflight
intents.propose majordomus intent propose POST /api/v1/intents/propose majordomus_intent_propose
intents.record majordomus intent show GET /api/v1/intents/record majordomus_intent_record
intents.validate majordomus intent validate GET /api/v1/intents/validate majordomus_intent_validate
intent_realization.explain majordomus intent explain GET /api/v1/intents/explain majordomus_intent_explain
intent_realization.work majordomus intent realization GET /api/v1/intents/realization majordomus_intent_realization
in the Cockpit, of a running server
/cockpit/intents Intents

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

Executable use cases

The rules that hold it

Using it

The commands that run it

  • majordomus plan begin

    The milestone and issue model — validate it, read it, and move one issue through it.

From the executable's command line

The synopsis of each, as the executable's own help prints it.

Where this page comes from

the file
.ai/repo/features/planning.md
the same answer
majordomus product show planning

Searches the titles and descriptions of every page this site publishes.