Skip to content
GRPNR.

Initial recommendation — pre-research expert take

Written BEFORE the full research pass, per brief. The research (02–14) must challenge this, not confirm it. Positions here are priors, dated 2026-07-18, grounded in plans/001-factory-apps-validation/ evidence [E1]–[E10] but not yet in fresh market research.

What the product fundamentally is

An accounting system, not an app. Work-ledger is a ledger in the bookkeeping sense: an append-friendly Postgres system of record where every unit of rebuild work has exactly one owner at a time, a permanent disposition, and an attributable cost. The primary users are agents, via API. Humans read it through Grafana and SQL. It is not a project-management tool, not a kanban board, not a UI product.

The temptation to resist from day one: turning it into a web app. The moment it grows screens, comments, priorities, and notifications, it becomes a worse Linear that two people use.

Who it serves first

  1. Robert’s fleet agents (10→64 concurrent Claude sessions) — claim units atomically, report transitions, record cost. The only users on the write path.
  2. Robert (operator) — queue depth, stall detection, cost/merged-unit, rework rate. Read path.
  3. Tomas (stakeholder) — disposition table at kill gates: what’s MIGRATED / DROPPED / DEFERRED / DEAD, with evidence links. Read-only, low frequency, high stakes.

The single most important customer problem

At fleet scale, unclaimed-and-untracked work destroys trust in the whole program. Two concurrent agents picking the same unit burn double tokens and produce merge collisions; an agent dying mid-unit leaves work silently half-done; cost accrues with no per-unit attribution; and abandoned migrations become invisible — the legacy estate already contains two half-finished stranglers rotting in code [E6]. That failure mode at 1-developer scale becomes fatal at 64-agent scale. The ledger exists so that no unit of work can be in an ambiguous state.

Simplest useful version

One Encore service in the internal plane. One schema. Three endpoints:

  • claim(unit) — atomic (PG advisory lock / FOR UPDATE SKIP LOCKED), returns full unit state, idempotent per agent.
  • transition(unit, state, evidence?) — enum-constrained state machine; illegal transitions rejected by the DB, not by convention.
  • block(unit, question) — parks the unit, emits the question toward triage.

Plus: disposition row types (absorbing the decommission ledger), a cost column written per attempt, two SQL views (queue depth, cost/unit), one Grafana panel. No UI. No auth beyond service-to-service. Shippable in days.

Primary user journey

Agent asks for work → claims unit → works in its worktree → transitions to verified (with parity evidence) or blocked (with question) → cost recorded → Robert watches queue/stall/cost panels → at each kill gate, Tomas reads the disposition table as the program’s evidence of record.

API-first, embedded. Typed Encore endpoints for agents; SQL views + Grafana for humans; occasional human writes via a trivial CLI or plain SQL. Not web, not mobile, not desktop, not conversational. The Grafana instance already mandated by the fleet-monitor verdict (research/12 §2) is the ledger’s entire human surface in v1.

UX/UI direction (Ive / Norman / Rams lenses)

  • Rams — less, but better; honest. The product’s quality lives in whether the numbers can be trusted, not in screens. Weniger aber besser here means: one metaphor (accounting), zero decoration, no interface at all where SQL suffices. An honest product does not pretend to be a PM tool.
  • Norman — affordances and error prevention at the schema layer. The API is the UX and agents are the users: states that cannot be misused (DB-enforced transitions), claims that cannot race (atomicity as an affordance), every call returning the full resulting state (feedback), errors that name the violated invariant (discoverability for LLM users — the error message is prompt engineering).
  • Ive — coherence carried through naming. One vocabulary end-to-end: ledger, entry, claim, disposition. [superseded: canon is unit / claim / attempt / disposition — see 10-architecture P4] Never “ticket”, “task” (collides with Zaruba’s tasks service), or “issue”. Complexity handled by the system (projection reconciliation, idempotency) rather than transferred to the user (no “please check if someone else is working on this” conventions).

What to remove from the initial concept

  • Any custom web UI, kanban, or board view — Grafana + Temporal’s admin UI cover reads.
  • Per-unit comments/chat — questions go to triage, decisions go to ADRs.
  • Priority algorithms, sprint/iteration concepts, assignee routing rules — queue order + claim is enough.
  • Embedding-based anything (that’s triage’s R&D, not the ledger’s).
  • Notifications — the monitor alerts; the ledger records.
  • Multi-tenancy, roles beyond the two-plane boundary, org management.

What should NOT be in the MVP

  • Projection from the workflow-execution stream (arrives when fleet units actually run as internal-plane Temporal workflows; v1 fleet = external Claude sessions using the external-claim endpoint — per architect addendum #1–2).
  • Evidence-file storage (links only; artifacts live in the harness/R2).
  • Cost roll-up dashboards beyond the two views (fleet monitor’s thin layer owns dashboards).
  • Any negotiated ask of Tomas (v1 must be zero-PR against the core plane).

Biggest usability risk

State-model drift — two sources of truth. If ledger state and Temporal execution state can disagree, the first disagreement during an incident kills trust in both (plan 001 pre-mortem #3). Second risk, same family: agents writing creative junk into free-text fields. Mitigations are structural: Temporal-owned fields are projection-only by construction; everything enumerable is an enum with CHECK constraints; free text is confined to question and evidence_url.

Fastest prototype that tests the concept

One day: the schema + claim() as a SQL function + a vitest integration test proving atomic claim under 2 concurrent claimers (Docker PG), plus a replayed-event projection test proving exactly-once transitions. That is also literally TDD step 1 of plan 001 — the prototype and the first production increment are the same artifact, which is the strongest sign the scope is right.

Platform verdict

API-first embedded service (Encore, internal plane), Grafana as the read surface. Revisit only if ≥3 humans need the disposition view interactively — then it’s one server-rendered table, not an app.

Prior to be tested by research

Plan 001 already scored this BUILD THIN with high confidence. The honest open questions the research must attack:

  1. Is even a thin service too much? Could beads / Backlog.md (research/12 §1.2), a bare pgmq/SKIP LOCKED table, or Temporal search-attributes + tasks svc + Grafana cover 90% for zero build? Where exactly do they fail (dispositions? cost attribution? cross-fleet visibility)?
  2. Is it a product or a schema? If the durable value is the data model + invariants, the minimal buildable thing might be a migration file + 200 lines of service code — and the “product” framing itself might be scope inflation.
  3. Does anyone besides Robert’s fleet ever adopt it? If Tomas’s fleet never claims through it, is a one-fleet ledger still worth owning? (Prior: yes — dispositions alone justify it — but that’s untested.)
  4. Sequencing — ledger before monitor, or monitor first (the committed deliverable) with the ledger as its data source?