Commission: what it is, and what a dashboard is for

Design brief. Everything a team needs before reimagining the human surface — the product, the primitives, the real data, and an honest account of five attempts that did not work.

Sources: docs/positioning.md (canonical), the codebase, and live data as of August 2026.

1. What Commission is

Commission turns goals into verified software by coordinating the task graph, execution environment, and shared context of humans and AI agents.

— canonical, docs/positioning.md

Shorter: the execution layer for software delivery. Shorter still, and the sentence that should drive every design decision here: agents operate it; humans are asked only for judgment.

It is a layer, not a tool. Something sits above it and something sits below it, and Commission owns the space between:

above	Commission	below
goals, intent, judgment, approval — humans, and the roadmap wherever it lives	the task graph, dispatch, claims, context, gates, evidence, the event log	whoever does the work — coding agents, humans, CI, the repo, the environment

The test for the category: can a machine operate the whole loop? Not read from it, not receive a webhook — operate it. Plan, claim, work, record, prove, close, pick up the next thing, with a person touched only where judgment is genuinely required.

What it is deliberately not

Not a coding agent. No model, no inference. It never writes code.
Not another Jira. No portfolio reporting, capacity planning, or workflow designer. It is the system of record for execution, not for the organisation.
Not AI project management. No generated summaries standing in for facts, no predicted dates, no AI-written tickets nobody asked for.
Not a metrics product. No story points, no velocity, no burndown, no forecast. These are refused by design, and a dashboard is exactly where they creep back in.

2. What it actually does

Eight primitives. Everything on any screen is a view of one of these.

primitive	what it means
task graph	One recursive unit of work — a task may have a parent, children, dependencies, acceptance criteria, evidence and a gate. There is no epic/story/subtask taxonomy. A task is a task at every level.
ready frontier	Everything workable right now: open, dependencies satisfied, children closed. Derived at query time, never stored. Claimable by many actors at once.
blocked	A derived condition, not a status. A task is blocked when a dependency is unsatisfied. It cannot be set or cleared by hand — so it can never be wrong.
claim / lease	Exclusive permission to work a task, taken atomically. Every claim expires (2h default), so a crashed session never wedges anything — it becomes reclaimable.
gate & evidence	A gate names the evidence kinds a task needs — a PR, a test run, a commit, a benchmark. Evidence is attached as data with a reference. ← the differentiator
refusal	A rejected action that states what is missing and the exact command that fixes it. Refusals are prompts, not errors.
context bundle	Everything needed to work a task in one read: body, criteria, dependency state, linked docs, evidence, prior notes, and the commands that finish it from here.
event log	Append-only. Everything that happened, per project and per task, read forward with a cursor. History is added to, never rewritten.

The one that matters most

done is a predicate, not a status. You cannot drag a card into it. commission done is refused until every acceptance criterion is ticked, the gate’s evidence kinds are attached with real references, child tasks are closed, and any required human approval is given — and the refusal names each missing thing and the command that supplies it.

This is the single fact that separates Commission from every tracker. If a person cannot see it on the dashboard, the dashboard is not showing the product.

3. Who is actually there

Two kinds of actor, and the split is the whole design problem.

Agents do the work. They claim tasks, write code, attach evidence, leave notes, close what they can. They run in parallel — five sessions at once is normal. They already have three interfaces: a CLI, a JSON API, and an MCP server. They do not need a dashboard and will never open one.

Humans own three things and nothing else: intent (what should be built), judgment (the calls an agent must not make alone), and approval (whether finished work is acceptable). Everything between those is Commission’s.

The product already encodes this. There are two dispatch commands and they serve different species:

next serves actors of kind agent; inbox serves actors of kind human. Both are derived from the same graph.

— canonical, positioning.md §6

next answers what should I work on — the ready frontier, ordered by policy, claimed atomically. inbox answers where is my judgment required — approvals, escalated questions, finished work awaiting acceptance, sessions that went quiet, disagreements with an external system.

4. Why a dashboard exists at all

Fair question, given agents are served three other ways. The honest answer has three parts.

Judgment is a human act and a terminal is a poor place to perform it. Accepting six finished tasks means reading what each one rests on and deciding. That is comparison work — eyes moving between things — and it is what screens are for.
Trust has to be earned visually. The pitch is that machines did the work and you can believe it. A person needs to see the evidence beside the completion, repeatedly, before they stop checking. No CLI output builds that.
Somebody has to be able to look without operating. A lead, a stakeholder, a founder on a phone. They will not learn a command.

So: the dashboard is the human surface, and control is minute. The real control surface is the CLI and the agents. What the dashboard has to be excellent at is judging, believing, and noticing.

The three questions it must answer

Does anything need me? And for each thing: what it is, why a person and not an agent, what it costs to leave it, and how to resolve it — without leaving the page.
Can I believe what it says is finished? The evidence beside the completion it justified. What was proven, what was forced, what closed on nothing.
What happened while I was away? Work runs unattended, often overnight. Coming back to a screen that looks identical to yesterday’s is the failure state.

A fourth is optional and secondary: what is the machine doing right now — the frontier, what can run in parallel, what is blocked on what. That is next’s worldview rendered for a curious person. It is legitimate, and it must not be the front door.

5. The value proposition

Three contrasts, each of which has to survive being argued.

Unlike Jira, Commission understands software

Jira’s model is a ticket: a title, free text, a status name, custom fields. Deliberately domain-agnostic — the same model runs a marketing campaign and a kernel port. That generality means it cannot compute the three things that matter: what is workable right now (a “blocks” link is a report nobody recomputes), what done requires (it can force a field to be non-empty; it cannot know the field is true), and where the work happens (repos, PRs, branches and touched files are first-class here, third-party decorations there).

Unlike coding agents, Commission remembers

An agent session starts cold and ends. Commission holds what was decided, what was tried, what was rejected and why — and hands it back in one read. The notes on a task are written for the next session, not for a reader today.

Unlike project tools, Commission executes

It dispatches. commission next --claim picks the highest-value workable task and claims it in one transaction, so N agents running the same command each get a different one, with no collisions and no coordinator.

The sentence a competitor cannot print

“121 tasks closed here. 113 carry their evidence. 54 carry a test. 2 were forced.”

Jira cannot say this, because its done is a column. This is the product’s soul, and it is the thing a dashboard is uniquely able to make felt.

6. The real data — design against this, not a fixture

Three live projects. They are shaped very differently, and any design that only works on one of them is not finished.

This is the single most expensive mistake made so far: every previous version was judged against a nine-task demo fixture with nothing closed and no hierarchy, which could not exhibit any of the conditions below.

project	tasks	closed	needs a person	shape
Commission	111	105	2	Almost no hierarchy — 96 roots, 1 parent. Structure lives in 93 dependencies.
GulfWeather	156	121	9	Real hierarchy — 45 roots, 28 parents, 71 dependencies. Goals with work under them.
Steer	26	1	5	Flat imported Jira. Barely used. One issue actively disagrees with Jira.

What that means for the design

The queue is small. Two, nine and five items. A screen staked entirely on that list is nearly blank on a healthy project — and the better the product works, the emptier it gets. An empty queue is the success state and must feel like an achievement, not a page that failed to load.
Most tasks are closed. 105 of 111, 121 of 156. The dominant material is history with evidence attached, not a backlog.
Hierarchy is optional. Anything premised on “your goals are parent tasks” collapses into a flat list on two of three projects.
Dependencies are the real structure on the largest project, and they are currently rendered as the string “waiting on relay-70, relay-95”. Nobody has ever designed this.
Projects go cold. Days pass with nothing moving. That is a state worth showing, and it is the state most often on screen.

7. What the backend can already hand you

Design freely — most of what a screen needs is already derived, composed in core, and served as JSON. Sentences are composed server-side on purpose: the CLI, the API and any UI must not word the same fact differently.

available	shape
situation	One or two sentences about a project’s state, a mood (`clear` / `attention` / `alarm`), 2–3 figures, and why that sentence fired. e.g. “Six finished tasks to accept, and three other things needing you. Nothing has moved in five days.”
inbox	The judgment queue. Nine kinds, ranked by how much work each unblocks. Every item carries four composed sentences — what it is, why a person, what it costs to ignore, and the one command — plus age and unblock count.
provenDone	Closed work with full evidence rows, who closed it, whether it was forced — plus a project-wide tally (closed / with evidence / with a test / forced).
doneGate	Per task: every requirement, met and unmet, in order, each with the exact command that satisfies it. The same function composes the CLI’s refusal.
board	Ready frontier with collision-free parallel batches, blocked with blockers, in-flight with holders and lease clocks, recently closed, recently cancelled with reasons.
watermark	Per-person “since you last looked”, advanced only by an explicit acknowledgement — never by rendering.
search / events	Full-text across every task; the append-only log with a cursor.

Gaps worth knowing: nothing recurses on parent/child, so there is no subtree rollup; dependency chains are not computed (only immediate blockers); there is no cross-project inbox. All are addable — flag them and they get built.

8. Vocabulary that must not be renamed

These words have fixed meanings across the CLI, the docs, the API and the marketing site. A surface that needs a different meaning is wrong, or needs a different word.

word	means
task	The one recursive unit. Not “ticket”, not “issue”, not “card”.
ready frontier	What is workable right now. Not “todo”, not “backlog”.
blocked	Derived from dependencies. Never a status somebody set.
claim / lease	Exclusive permission, with an expiry. Not “assigned” — assignment is ownership and outlives a claim.
gate / evidence	The requirement / the satisfaction. Never one for the other.
refusal	A rejection that names the fix. Not an error.
ask / answer	An agent escalating rather than guessing, and the human decision that resolves it.
actor	Whoever acted, human or agent, recorded on everything.

9. Five attempts, and why each failed

Written down so the sixth does not repeat them. All were rejected by the product’s owner.

A board with status columns. Rendered the ready frontier, parallel batches and status buckets as the front door. That is next’s worldview — the agent’s question — so it came out as Jira with better type. (wrong audience)
The same board, restyled. Better colour, better spacing, same information architecture. Verdict: “you see the pages, they’re ugly… this isn’t a standard task management product.” (styling cannot fix architecture)
Reorganised around behaviours. Content genuinely improved — the queue was promoted over the board, proof got a section. But everything was still set at 12–14px: 120 of 134 font-size declarations were two adjacent sizes, and the largest element on the page was the project’s name — a constant, in the biggest type, identical on every visit, above everything that actually changed.
A full front-end rewrite in the marketing site’s design language: hairline rules, editorial spacing, one typographic column. Correct for a page read once; wrong for a tool operated daily. Verdict: “looks like 2008 Bootstrap.” (document, not instrument)
An app shell — sidebar, tinted ground, elevated surfaces, dense rows, status pills. Structurally right and roughly 3× denser. Verdict: “still so ugly.” At which point the honest conclusion was that the taste calls needed people, which is why this document exists.

The transferable lessons

The audience is the human’s three jobs. Anything organised around dispatch is built for a reader who will never open it.
A tool is not a document. Editorial spacing and rules read as dated the moment they are applied to something operated daily.
The biggest thing on screen should be the most variable fact, never a constant.
Judge every design against real data — 156 tasks, 121 closed, a queue of nine — not a demo.
Justification is a property of a kind, not an item. Six things needing the same call must not print the same sentence six times.

10. Constraints

Technical

Ships as a single binary + a SQLite file. No network, no CDN, no static directory. Fonts and assets are compiled in.
Runs on localhost by default; also servable to a small team with real accounts.
Currently Preact + Tailwind bundled into the binary — changeable, but the no-runtime-dependency rule is not.
Light and dark are both first-class. Light is the default.

Product

A view may not compute a fact core derives. If a screen needs something, core returns it — the UI never re-implements it.
Composed sentences render verbatim. No surface rewords an obligation.
No forecasts, velocity, burndown or health scores. Ever.
Colour is never the only signal.
An agent must never be able to give an approval — enforced in core, not in the UI.

11. Open questions worth the team’s time

What does an empty queue look like? It is the success state and the most common one. It should feel like an achievement.
How do you show a dependency graph that is 93 edges deep and currently a comma-separated list of ids?
What does proof look like at volume? A hundred rows of test=green · commit=7d7d5a4 is not something anyone reads. The tally is a sentence; is there a better form?
Is “project” the right top-level object, or is the estate one continuous queue across all of them?
What is the phone experience? Approving from a phone is plausibly the highest-value interaction in the product and has never been designed.
Where does planning live? Creating work is a CLI flow today. Should a person be able to state intent here?
How much of the machine is worth showing? Parallel batches and leases are genuinely differentiating and genuinely nobody’s daily concern.

If you read one thing

Commission does not write your code and does not replace your judgment; it is the layer everything else runs on.

— canonical, positioning.md

The dashboard is where the judgment half of that sentence happens. Its job is to make a person confident that machines did the work correctly, ask them for the few calls that are genuinely theirs, and otherwise stay out of the way. Everything else is decoration.

This page is docs/design/dashboard-brief.md in the Commission repository, rendered in place — the site keeps no copy of it. The repository is private, so there is no edit link to follow.