feat: capacity-aware scheduling (#8) — real focus factors drive every forecast

Turns the single-serial-worker scheduler into a capacity-aware, multi-lane one.
Configured team members become lanes; an issue runs on its assignee's lane (or the
earliest-free lane), its duration scaled by that lane's throughput
(focusFactor × allocation). Every forecast — Focus cone, Runway, milestone
drill-in — is now capacity-aware.

core (@commitea/core):
- capacity/capacity-v0: CapacityMember + capacityPerWorkday + parseCapacityConfig
  (clamps, drops invalid; degrades to []).
- scheduler/scheduler-capacity-v0: scheduleWithCapacity reuses the v0 topo order +
  critical path, re-lays work across lanes (layoutOnLanes, resolveLanes, makespan).
  Empty workers → the single serial plan verbatim.
- forecast() gains options.workers: each MC trial lays sampled durations across the
  lanes and takes the makespan; serial path unchanged. SchedulableIssue gains
  assignee; ScheduledItem gains worker.
- 11 new tests (parse/clamp, parallelism halves makespan, speed scaling, assignee
  routing, cross-lane deps, forecast makespan shrinks with lanes).

app:
- pm-state capacity/members.json read (readCapacity + pmstate:capacity bridge);
  useCapacity hook → workers; forecastBacklog/runwayView/milestoneView pass workers.
- Runway Capacity card shows the real config (person · focus · alloc · pd/day).

Config lives in pm-state (D4); seeded christian(0.8)/stephen(0.6×0.5). Degrades to
the fixture/serial when absent.

Verified: 128 core tests green, desktop typecheck clean, 14 fixture e2e green. Live:
the capacity card is real, and the P2 forecast shifts 32d→37d — honest, since real
focus factors (<1) replace the v0 focus-1.0 assumption.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

apps/desktop/src/main/gitea.ts

@@ -20,6 +20,7 @@ import {
   type IssueChange,
   type LifecycleEvent,
   makeDirectiveEntry,
+  parseCapacityConfig,
   parseDirectiveLog,
   planIssueChange,
   type ProjectSnapshot,
@@ -109,6 +110,19 @@ export async function readDirectives(client: GiteaClient) {
   return parseDirectiveLog(text)
 }
 
+const CAPACITY_PATH = 'capacity/members.json'
+
+/** Read the capacity config from the pm-state repo (empty when absent). */
+export async function readCapacity(client: GiteaClient) {
+  const file = await client.getFile(CAPACITY_PATH)
+  if (!file) return []
+  try {
+    return parseCapacityConfig(JSON.parse(Buffer.from(file.contentBase64, 'base64').toString('utf8')))
+  } catch {
+    return []
+  }
+}
+
 /** Full reconcile: issues + milestones + native deps + lifecycle timelines. */
 export async function reconcileSnapshot(
   client: GiteaClient,
@@ -266,4 +280,15 @@ export function registerGiteaIpc(): void {
       return { ok: false as const, reason: 'error' as const, message: e instanceof Error ? e.message : String(e) }
     }
   })
+
+  // Read the capacity config from the pm-state repo (for capacity-aware forecasts).
+  ipcMain.handle('pmstate:capacity', async () => {
+    const pm = getPmStateClient()
+    if (!pm) return { ok: false as const, reason: 'unconfigured' as const, members: [] }
+    try {
+      return { ok: true as const, members: await readCapacity(pm) }
+    } catch {
+      return { ok: true as const, members: [] }
+    }
+  })
 }

apps/desktop/src/preload/index.ts

@@ -19,6 +19,8 @@ const api = {
   pmstate: {
     /** Read the directive ledger from the pm-state repo. */
     directives: () => ipcRenderer.invoke('pmstate:directives'),
+    /** Read the capacity config from the pm-state repo. */
+    capacity: () => ipcRenderer.invoke('pmstate:capacity'),
   },
   model: {
     /** Whether a model endpoint is configured (else the UI keeps the scripted Reginald). */

apps/desktop/src/renderer/src/components/screens/runway-screen.tsx

@@ -1,23 +1,35 @@
 import React from 'react'
 
+import { type CapacityMember, capacityPerWorkday } from '@commitea/core'
+
 import { RunwayBar } from '../charts/chart.js'
 import { Card, Badge, Tag, Icon, IconButton } from '../ui/index.js'
 import { RUNWAY, CAPACITY, type RunwayMilestone } from '../../data/fixtures.js'
 
 // Runway — capacity vs milestone dates; ranges, never points.
-// `milestones` (real per-milestone forecasts) overrides the demo when present.
+// `milestones` (real per-milestone forecasts) + `capacity` (real config) override the demo.
 export function RunwayScreen({
   onOpenCalibration,
   onOpenMilestone,
   calibration,
   milestones,
+  capacity,
 }: {
   onOpenCalibration: () => void
   onOpenMilestone: (id?: number) => void
   calibration?: { n: number; coldStart: boolean }
   milestones?: RunwayMilestone[]
+  capacity?: CapacityMember[]
 }) {
   const rows = milestones && milestones.length ? milestones : RUNWAY
+  const capacityRows =
+    capacity && capacity.length
+      ? capacity.map((m) => ({
+          who: m.person,
+          slices: `focus ${m.focusFactor} · alloc ${Math.round(m.allocation * 100)}%`,
+          hours: `${capacityPerWorkday(m).toFixed(2)} pd/day`,
+        }))
+      : CAPACITY
   const calibNote = calibration
     ? calibration.coldStart
       ? `cold-start priors · ${calibration.n}/20 closed issues estimated`
@@ -59,7 +71,7 @@ export function RunwayScreen({
       <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 14, alignItems: 'start' }}>
         <Card overline="Capacity" flush>
           <div>
-            {CAPACITY.map((p, i) => (
+            {capacityRows.map((p, i) => (
               <div key={p.who} style={{
                 display: 'flex', alignItems: 'center', gap: 12, padding: '12px 20px',
                 borderTop: i === 0 ? 'none' : '1px solid var(--line-1)',

apps/desktop/src/renderer/src/components/shell/app-shell.tsx

@@ -6,6 +6,7 @@ import type { IssueChange } from '@commitea/core'
 import type { IssueRef } from '../../data/fixtures.js'
 import {
   backlogCalibration,
+  capacityWorkers,
   forecastBacklog,
   issuesToBoardColumns,
   milestoneView,
@@ -13,6 +14,7 @@ import {
   scheduleFocus,
 } from '../../lib/backlog.js'
 import { useBacklog } from '../../lib/use-backlog.js'
+import { useCapacity } from '../../lib/use-capacity.js'
 import { PrimitivesGallery } from '../gallery.js'
 import { BoardScreen } from '../screens/board-screen.js'
 import { CalibrationScreen } from '../screens/calibration-screen.js'
@@ -96,6 +98,8 @@ export function AppShell() {
   const [readIds, setReadIds] = useState<number[]>([])
   const [milestoneId, setMilestoneId] = useState<number | null>(null)
   const [backlog, refetchBacklog] = useBacklog()
+  const capacityMembers = useCapacity()
+  const workers = capacityWorkers(capacityMembers)
   const boardColumns =
     backlog.status === 'ready' ? issuesToBoardColumns(backlog.issues, backlog.timelines) : undefined
   const focus =
@@ -104,10 +108,12 @@ export function AppShell() {
     backlog.status === 'ready' ? backlogCalibration(backlog.issues, backlog.timelines) : undefined
   const forecast =
     backlog.status === 'ready'
-      ? (forecastBacklog(backlog.issues, backlog.deps, new Date(), calibration?.model) ?? undefined)
+      ? (forecastBacklog(backlog.issues, backlog.deps, new Date(), calibration?.model, workers) ?? undefined)
       : undefined
   const runwayMilestones =
-    backlog.status === 'ready' ? runwayView(backlog.issues, backlog.milestones, backlog.deps) : undefined
+    backlog.status === 'ready'
+      ? runwayView(backlog.issues, backlog.milestones, backlog.deps, new Date(), workers)
+      : undefined
   const milestone =
     backlog.status === 'ready' && milestoneId != null
       ? (milestoneView(
@@ -117,6 +123,8 @@ export function AppShell() {
           backlog.deps,
           backlog.timelines,
           calibration?.model,
+          new Date(),
+          workers,
         ) ?? undefined)
       : undefined
 
@@ -221,6 +229,7 @@ export function AppShell() {
             }}
             calibration={calibration ? { n: calibration.model.n, coldStart: calibration.model.coldStart } : undefined}
             milestones={runwayMilestones}
+            capacity={capacityMembers}
           />
         )
       case 'calibration':

apps/desktop/src/renderer/src/global.d.ts

@@ -1,5 +1,6 @@
 import type {
   AgentStep,
+  CapacityMember,
   ChangeProposal,
   ChatMessage,
   CaptureProposal,
@@ -77,9 +78,15 @@ export type DirectivesResult =
   | { ok: false; reason: 'unconfigured' | 'error'; message?: string }
   | { ok: true; directives: DirectiveRecord[] }
 
+/** The result of reading the capacity config. */
+export type CapacityResult =
+  | { ok: false; reason: 'unconfigured'; members: CapacityMember[] }
+  | { ok: true; members: CapacityMember[] }
+
 /** The pm-state bridge (machine-derived state) exposed by the preload over IPC. */
 export interface PmStateBridge {
   directives(): Promise<DirectivesResult>
+  capacity(): Promise<CapacityResult>
 }
 
 declare global {

apps/desktop/src/renderer/src/lib/backlog.ts

@@ -2,10 +2,13 @@ import {
   type CalibrationModel,
   type CalibrationSample,
   calibrationSamples,
+  type CapacityMember,
+  capacityPerWorkday,
   COLD_START_THRESHOLD,
   type DependencyEdge,
   fitCalibration,
   forecast,
+  type Worker,
   type GiteaIssue,
   type GiteaMilestone,
   inferLifecycle,
@@ -107,9 +110,15 @@ function toSchedulable(issues: GiteaIssue[]) {
       labels: i.labels,
       estimateDays: i.facts.estimateDays,
       priority: i.facts.priority,
+      assignee: i.assignee,
     }))
 }
 
+/** gitea CapacityMembers → scheduler lanes (person + throughput). */
+export function capacityWorkers(members: CapacityMember[]): Worker[] {
+  return members.map((m) => ({ person: m.person, speed: capacityPerWorkday(m) }))
+}
+
 export interface ForecastView {
   scope: number
   cone: BurnUpData
@@ -132,9 +141,10 @@ export function forecastBacklog(
   deps: DependencyEdge[],
   today: Date = new Date(),
   calibration?: CalibrationModel,
+  workers: Worker[] = [],
 ): ForecastView | null {
   const model = calibration ? toDurationModel(calibration) : undefined
-  const f = forecast(toSchedulable(issues), deps, model ? { model } : {})
+  const f = forecast(toSchedulable(issues), deps, { ...(model ? { model } : {}), workers })
   const cone = buildBurnUpData(f, today)
   if (!cone) return null
   return {
@@ -252,6 +262,7 @@ export function runwayView(
   milestones: GiteaMilestone[],
   deps: DependencyEdge[],
   today: Date = new Date(),
+  workers: Worker[] = [],
 ): RunwayMilestone[] {
   const open = issues.filter((i) => i.state === 'open')
   const rows = milestones
@@ -266,8 +277,10 @@ export function runwayView(
           labels: i.labels,
           estimateDays: i.facts.estimateDays,
           priority: i.facts.priority,
+          assignee: i.assignee,
         })),
         deps,
+        { workers },
       )
       const p90 = f.curve.length ? f.curve[f.curve.length - 1].p90Day : f.p95Day
       const dueDay = m.dueOn ? workingDaysBetween(today, new Date(m.dueOn)) : null
@@ -324,6 +337,7 @@ export function milestoneView(
   timelines: Timelines = {},
   calibration?: CalibrationModel,
   today: Date = new Date(),
+  workers: Worker[] = [],
 ): MilestoneView | null {
   const m = milestones.find((x) => x.id === id)
   if (!m) return null
@@ -340,9 +354,10 @@ export function milestoneView(
       labels: i.labels,
       estimateDays: i.facts.estimateDays,
       priority: i.facts.priority,
+      assignee: i.assignee,
     })),
     deps,
-    model ? { model } : {},
+    { ...(model ? { model } : {}), workers },
   )
   const cone = buildBurnUpData(f, today)
 

apps/desktop/src/renderer/src/lib/use-capacity.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react'
+
+import type { CapacityMember } from '@commitea/core'
+
+/**
+ * The team's capacity config from the pm-state repo. Empty when unconfigured —
+ * forecasts then fall back to a single serial worker. Read once on mount.
+ */
+export function useCapacity(): CapacityMember[] {
+  const [members, setMembers] = useState<CapacityMember[]>([])
+  useEffect(() => {
+    let alive = true
+    window.commitea.pmstate
+      .capacity()
+      .then((r) => {
+        if (alive) setMembers(r.members)
+      })
+      .catch(() => {})
+    return () => {
+      alive = false
+    }
+  }, [])
+  return members
+}