@alecsibilia/luca 14.0.0-alpha.3 → 14.0.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.4
+
+No changes in this release.
+
 ## 14.0.0-alpha.3
 
 No changes in this release.

package/board/client/board-panel.tsx

@@ -118,6 +118,9 @@ const LENS_STAGES: { stage: LensState; title: string; icon: string }[] = [
 /** A card or stage key. */
 type Key = string
 
+/** The key of the fold for tickets left out for a person (#499). */
+const FOR_A_PERSON: Key = 'for_a_person'
+
 type DotKind = 'done' | 'current' | 'todo' | 'skip' | 'stopped'
 
 const makeStyles = ({
@@ -1063,11 +1066,12 @@ export const BoardPanel = ({
     )
     const [folded, setFolded] = useState<ReadonlySet<Key>>(
         () =>
-            new Set(
-                TICKET_STAGES.filter((entry) => entry.folded).map(
+            new Set<Key>([
+                ...TICKET_STAGES.filter((entry) => entry.folded).map(
                     (entry) => entry.stage
-                )
-            )
+                ),
+                FOR_A_PERSON,
+            ])
     )
     const look = { theme, styles }
     const state = board.data?.selected ?? null
@@ -1293,6 +1297,39 @@ export const BoardPanel = ({
                 )
             })}
 
+            {state.for_a_person.length > 0 ? (
+                <Section styles={styles}>
+                    <StageHeader
+                        title="For a person"
+                        hint="left out of this run: a person does these, or they wait on one"
+                        icon="User"
+                        count={state.for_a_person.length}
+                        color={theme.colors.foregroundMuted}
+                        folded={folded.has(FOR_A_PERSON)}
+                        onPress={() =>
+                            setFolded((set) =>
+                                toggled({ set, key: FOR_A_PERSON })
+                            )
+                        }
+                        {...look}
+                    />
+                    {folded.has(FOR_A_PERSON) ? null : (
+                        <View style={styles.stageBody}>
+                            {state.for_a_person.map((ticket) => (
+                                <Text
+                                    key={ticket.number}
+                                    style={styles.muted}
+                                    numberOfLines={2}
+                                >
+                                    #{ticket.number} {ticket.title} ·{' '}
+                                    {ticket.why}
+                                </Text>
+                            ))}
+                        </View>
+                    )}
+                </Section>
+            ) : null}
+
             {showsFinalReview({ state }) ? (
                 <>
                     <View style={styles.rule} />

package/board/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.3",
+    "version": "14.0.0-alpha.4",
     "private": true,
     "type": "module"
 }

package/board/server/board-vocabulary.ts

@@ -48,6 +48,26 @@ const TestRunSchema = z.looseObject({
 
 const WorktreeSchema = z.looseObject({ branch: z.string() })
 
+/**
+ * The open tickets intake left out for a person (#499): `for_a_person`, or
+ * `waits_on_person` with the tickets for a person it `waits_on`, and the
+ * blockers it waits `through`. Missing in older journals.
+ */
+const LeftOutListSchema = z
+    .array(
+        z.looseObject({
+            number: z.number().int(),
+            title: z.string().catch(''),
+            reason: z.enum(['for_a_person', 'waits_on_person']),
+            waits_on: z.array(z.number().int()).catch([]).default([]),
+            through: z.array(z.number().int()).catch([]).default([]),
+        })
+    )
+    .catch([])
+    .default([])
+
+export type LeftOutList = z.infer<typeof LeftOutListSchema>
+
 const tokenCount = z.number().min(0).catch(0)
 
 /** One plan window's reading: `utilization` 0 to 1, `resetsAt` in seconds. */
@@ -128,13 +148,19 @@ export const BOARD_VOCABULARY = {
             })
         ),
     }),
-    /** The run ends with nothing to do; `already_done` is empty at intake (#484). */
+    /**
+     * The run ends with nothing to do; `already_done` is empty at intake
+     * (#484), and `left_out` names the tickets left for a person (#499).
+     */
     nothing_to_do: z.looseObject({
         already_done: z.array(z.number().int()).catch([]).default([]),
+        left_out: LeftOutListSchema,
     }),
     spec_snapshot: z.looseObject({
         spec: z.looseObject({ number: z.number(), title: z.string() }),
         ticket_order: z.array(z.number()).catch([]),
+        /** The tickets left out for a person (#499); older journals have none. */
+        left_out: LeftOutListSchema,
     }),
     ticket_snapshot: z.looseObject({
         number: z.number().int(),

package/board/server/luca-version.ts

@@ -1,2 +1,2 @@
 /** The Luca version of this board, stamped when the package was packed. */
-export const LUCA_VERSION: string = "14.0.0-alpha.3"
+export const LUCA_VERSION: string = "14.0.0-alpha.4"

package/board/server/make-rows.ts

@@ -5,6 +5,7 @@ import {
     failureText,
     finalReasonText,
     LEARNER,
+    numbersText,
     reasonText,
     RETRY_REFUSED_TEXT,
     rebasedText,
@@ -186,6 +187,44 @@ const ignoredText = ({
     }
 }
 
+/**
+ * Why a run ended with nothing to do: its tickets were already done (#484),
+ * or what is open is for a person or waits on one (#499), or the spec has
+ * no open tickets.
+ */
+const nothingToDoText = ({
+    content,
+}: {
+    content: Extract<BoardRecord, { kind: 'nothing_to_do' }>['content']
+}): string => {
+    const numbersOf = (reason: 'for_a_person' | 'waits_on_person') =>
+        content.left_out
+            .filter((ticket) => ticket.reason === reason)
+            .map(({ number }) => number)
+    const people = numbersOf('for_a_person')
+    const waiting = numbersOf('waits_on_person')
+    const done = content.already_done
+    const parts = [
+        done.length === 0
+            ? ''
+            : `the work of ${done.map((number) => `#${number}`).join(', ')} was already on the base branch`,
+        people.length === 0
+            ? ''
+            : `${numbersText({ numbers: people })} ${people.length === 1 ? 'is' : 'are'} for a person`,
+        waiting.length === 0
+            ? ''
+            : `${numbersText({ numbers: waiting })} ${waiting.length === 1 ? 'waits' : 'wait'} on a ticket for a person`,
+    ].filter((part) => part !== '')
+    if (parts.length === 0)
+        return 'Nothing to do: the spec has no open tickets.'
+    const last = parts.at(-1) ?? ''
+    const text =
+        parts.length === 1
+            ? last
+            : `${parts.slice(0, -1).join(', ')}, and ${last}`
+    return `Nothing to do: ${text}.`
+}
+
 /**
  * What a record means in one line, or `null` for records that are noise in
  * a chat (snapshots, session summaries, a clean leftover scan, Jev in shadow
@@ -218,21 +257,22 @@ export const describeRecord = ({
                 text: `Intake refused the run. ${after.run.refusal.join('; ')}`,
                 tone: 'danger',
             })
-        case 'nothing_to_do': {
-            const done = record.content.already_done
+        case 'nothing_to_do':
             return event({
-                text:
-                    done.length === 0
-                        ? 'Nothing to do: the spec has no open tickets.'
-                        : `Nothing to do: the work of ${done.map((number) => `#${number}`).join(', ')} was already on the base branch.`,
+                text: nothingToDoText({ content: record.content }),
                 tone: 'info',
             })
-        }
-        case 'spec_snapshot':
+        case 'spec_snapshot': {
+            const { spec, ticket_order, left_out } = record.content
+            const people =
+                left_out.length === 0
+                    ? ''
+                    : ` ${left_out.length} left for a person: ${left_out.map(({ number }) => `#${number}`).join(', ')}.`
             return event({
-                text: `Intake passed: spec #${record.content.spec.number}, ${record.content.ticket_order.length} tickets.`,
+                text: `Intake passed: spec #${spec.number}, ${ticket_order.length} tickets.${people}`,
                 tone: 'success',
             })
+        }
         case 'run_branch_created':
             return event({
                 text: `The run branch ${record.content.branch} is ready.`,

package/board/server/reduce-board.ts

@@ -1,4 +1,4 @@
-import type { BoardRecord } from './board-vocabulary'
+import type { BoardRecord, LeftOutList } from './board-vocabulary'
 
 import {
     ALL_STEPS_DONE,
@@ -16,6 +16,7 @@ import {
     type FindingCounts,
     type LensCard,
     type NeedsYou,
+    type PersonTicket,
     type PlanUsed,
     type RunInfo,
     type RunStatus,
@@ -208,6 +209,7 @@ export const createBoardState = ({
         started_on: null,
         version_note: null,
     },
+    for_a_person: [],
     usage: null,
     usage_label: USAGE_LABEL,
     run_tokens: 0,
@@ -236,6 +238,47 @@ export const createBoardState = ({
     latest: null,
 })
 
+/** Issue numbers as `#12`, `#12 and #13`, or `#12, #13 and #14`. */
+export const numbersText = ({ numbers }: { numbers: number[] }): string => {
+    const refs = numbers.map((number) => `#${number}`)
+    const last = refs.at(-1) ?? ''
+    return refs.length <= 1
+        ? last
+        : `${refs.slice(0, -1).join(', ')} and ${last}`
+}
+
+/**
+ * The tickets left out for a person (#499), with why in words, as the
+ * engine's PR says it.
+ *
+ * @example
+ * personTickets({ left_out: [{ number: 13, title: 'Link', reason: 'waits_on_person', waits_on: [12], through: [] }] })
+ * // [{ number: 13, title: 'Link', why: 'waits on #12, which is for a person' }]
+ */
+const personTickets = ({
+    left_out,
+}: {
+    left_out: LeftOutList
+}): PersonTicket[] =>
+    left_out.map(({ number, title, reason, waits_on, through }) => {
+        if (reason === 'for_a_person') {
+            return { number, title, why: 'for a person' }
+        }
+        const which =
+            waits_on.length === 1
+                ? 'which is for a person'
+                : 'which are for a person'
+        const via =
+            through.length === 0
+                ? ''
+                : ` (through ${numbersText({ numbers: through })})`
+        return {
+            number,
+            title,
+            why: `waits on ${numbersText({ numbers: waits_on })}, ${which}${via}`,
+        }
+    })
+
 const newTicket = ({
     number,
     title,
@@ -842,10 +885,19 @@ const applyKind = ({
                 },
             }
         case 'nothing_to_do':
-            return { ...state, run: { ...state.run, phase: 'nothing_to_do' } }
+            return {
+                ...state,
+                for_a_person: personTickets({
+                    left_out: record.content.left_out,
+                }),
+                run: { ...state.run, phase: 'nothing_to_do' },
+            }
         case 'spec_snapshot':
             return {
                 ...state,
+                for_a_person: personTickets({
+                    left_out: record.content.left_out,
+                }),
                 run: {
                     ...state.run,
                     spec_number: record.content.spec.number,

package/board/shared/board-state.ts

@@ -544,8 +544,27 @@ export const NO_MEMORY: MemoryCounts = {
     failed: 0,
 }
 
+/**
+ * An open ticket the run left out for a person (#499): one labeled
+ * `ready-for-human`, or one waiting on such a ticket. Not a problem, so the
+ * board lists it calmly and nobody is asked to act.
+ */
+export const PersonTicketSchema = z.object({
+    number: z.number().int(),
+    title: z.string(),
+    /** Why, in words: `for a person`, or `waits on #12, which is for a person`. */
+    why: z.string(),
+})
+
+export type PersonTicket = z.infer<typeof PersonTicketSchema>
+
 export const BoardStateSchema = z.object({
     run: RunInfoSchema,
+    /**
+     * The open tickets left out for a person (#499), by number. Defaulted,
+     * so an older board state still parses.
+     */
+    for_a_person: z.array(PersonTicketSchema).default([]),
     usage: UsageSchema.nullable(),
     /** What `usage` is, in words. Defaulted, so an older board state still parses. */
     usage_label: z.string().default(USAGE_LABEL),

package/engine/cli/run-modes.ts

@@ -18,6 +18,7 @@ import {
     startRun,
     STOP_ACTIONS,
 } from '../core/execute'
+import { nothingToDoText } from '../core/left-out'
 import { createGitAdapter } from '../git/git-adapter'
 import { createTypeSafeJev } from '../jev/jev-client'
 import type { JevShadow } from '../jev/jev-shadow'
@@ -50,8 +51,17 @@ export const DEMO_TURN_DELAY_MS = 1500
 const errorText = (error: unknown): string =>
     error instanceof Error ? error.message : String(error)
 
-/** What a run's last action means for the person watching it. */
-const endOf = ({ action }: { action: EngineAction }): RunEnd => {
+/**
+ * What a run's last action means for the person watching it. A run with
+ * nothing to do says why, from its `nothing_to_do` record in `records`.
+ */
+const endOf = ({
+    action,
+    records,
+}: {
+    action: EngineAction
+    records: JournalRecord[]
+}): RunEnd => {
     if (action.type === 'invalid_journal') {
         return {
             ok: false,
@@ -70,11 +80,24 @@ const endOf = ({ action }: { action: EngineAction }): RunEnd => {
                 ok: true,
                 message: `PR opened: ${action.pull_request.url}`,
             }
-        case 'nothing_to_do':
+        case 'nothing_to_do': {
+            const end = records.findLast(
+                (record) => record.kind === 'nothing_to_do'
+            )
             return {
                 ok: true,
-                message: 'Nothing to do: every ticket of the spec is closed.',
+                message: nothingToDoText({
+                    content:
+                        end?.kind === 'nothing_to_do'
+                            ? end.content
+                            : {
+                                  closed_tickets: [],
+                                  already_done: [],
+                                  left_out: [],
+                              },
+                }),
             }
+        }
         case 'refused':
             return {
                 ok: false,
@@ -157,7 +180,8 @@ const driveRun = async ({
 }): Promise<RunEnd> => {
     let end: RunEnd
     try {
-        end = endOf({ action: await run() })
+        const action = await run()
+        end = endOf({ action, records: journal.read() })
     } catch (error) {
         const message = errorText(error)
         // A launcher stop is journaled as run_stopped, then thrown.

package/engine/cli/setup.ts

@@ -25,10 +25,9 @@ import {
 import { safeMemory, type MemoryClient } from '../memory/memory-client'
 import { runCommand } from '../shell/run-command'
 import {
-    NEEDS_INFO_LABEL,
-    READY_LABEL,
-    REFACTOR_LABEL,
+    RELEASE_LABEL_DEFINITIONS,
     RELEASE_LABELS,
+    RUN_LABELS,
     type Tracker,
 } from '../tracker/tracker'
 
@@ -86,56 +85,14 @@ export type SetupEnd = {
     doctor: DoctorCheck[]
 }
 
-/** The labels a run needs, with what they're for. */
-const LABELS = [
-    {
-        name: READY_LABEL,
-        color: '0e8a16',
-        description: 'Ready for a Luca run',
-    },
-    {
-        name: REFACTOR_LABEL,
-        color: '5319e7',
-        description: 'Changes shape, not behavior: no new tests',
-    },
-    {
-        name: NEEDS_INFO_LABEL,
-        color: 'd93f0b',
-        description: 'Luca needs more detail before it can build this',
-    },
-]
-
-/** The version-bump labels a repo with changesets gets, one per bump. */
-const RELEASE_LABEL_INFO: Record<
-    (typeof RELEASE_LABELS)[number],
-    { color: string; description: string }
-> = {
-    'release:patch': {
-        color: 'c2e0c6',
-        description: "A patch bump for this spec's changeset (the default)",
-    },
-    'release:minor': {
-        color: 'fbca04',
-        description: "A minor bump for this spec's changeset",
-    },
-    'release:major': {
-        color: 'b60205',
-        description: "A major bump for this spec's changeset",
-    },
-    'release:none': {
-        color: 'ededed',
-        description: 'No version bump: an empty changeset',
-    },
-}
-
 /** Where a repo that uses changesets keeps their config. */
 const CHANGESET_CONFIG_FILE = join('.changeset', 'config.json')
 
 /** The labels `repo` needs: the run's, plus the release ones with changesets. */
 const labelsFor = async ({ repo }: { repo: string }) => [
-    ...LABELS,
+    ...RUN_LABELS,
     ...((await Bun.file(join(repo, CHANGESET_CONFIG_FILE)).exists())
-        ? RELEASE_LABELS.map((name) => ({ name, ...RELEASE_LABEL_INFO[name] }))
+        ? RELEASE_LABELS.map((name) => RELEASE_LABEL_DEFINITIONS[name])
         : []),
 ]
 
@@ -601,7 +558,7 @@ const list = (lines: string[]): string =>
 
 /**
  * Gets `repo` ready for Luca. It creates the missing `ready-for-agent`,
- * `refactor`, and `needs-info` labels, and in a repo with
+ * `ready-for-human`, `refactor`, and `needs-info` labels, and in a repo with
  * `.changeset/config.json` the `release:*` ones too; writes a starting
  * `.luca/config.json` from `package.json` when there is none (see
  * `guessChecks`), with the repo's GitHub name as its `muninn.vault`, rewrites an old-Luca config into the new shape keeping

package/engine/core/already-done.ts

@@ -3,7 +3,7 @@ import type {
     DoneCommit,
     TestWriterResult,
 } from '../agents/role-results'
-import type { TicketSnapshot } from '../intake/intake-schemas'
+import type { LeftOutTicket, TicketSnapshot } from '../intake/intake-schemas'
 
 /**
  * A ticket whose work is already on the base branch (#484): its
@@ -30,11 +30,13 @@ export type AlreadyDoneAction =
     /**
      * End the run with nothing to do: at intake (`already_done` is empty),
      * or once every ticket's work was already done and those are closed.
+     * At intake, `left_out` names the open tickets left for a person (#499).
      */
     | {
           type: 'finish_nothing_to_do'
           closed_tickets: number[]
           already_done: number[]
+          left_out?: LeftOutTicket[]
       }
 
 /**

package/engine/core/decide.ts

@@ -196,6 +196,7 @@ const decideIntake = ({ state }: { state: RunState }): EngineAction => {
                     type: 'finish_nothing_to_do',
                     closed_tickets: result.closed_tickets,
                     already_done: [],
+                    left_out: result.left_out,
                 }
             }
             // A snapshot cut short by a crash is taken again in full; replay

package/engine/core/execute-stuck.ts

@@ -15,7 +15,11 @@ import {
     postCommentOnce,
     type CommentStep,
 } from '../tracker/post-comment-once'
-import type { Tracker, TrackerIssue } from '../tracker/tracker'
+import {
+    HUMAN_LABEL,
+    type Tracker,
+    type TrackerIssue,
+} from '../tracker/tracker'
 
 /**
  * How long the engine waits between reads of the spec issue while stuck
@@ -303,6 +307,16 @@ export const retryTicket = async ({
                   (ticket) => ticket.number === number
               )
             : undefined
+    const leftOut = (
+        checked.outcome === 'passed'
+            ? checked.snapshot.left_out
+            : checked.left_out
+    ).some((ticket) => ticket.number === number)
+    if (fresh === undefined && leftOut) {
+        return refuse([
+            `The ticket is now for a person (\`${HUMAN_LABEL}\`), or waits on one, so a run can't build it.`,
+        ])
+    }
     if (fresh === undefined) return refuse(['The ticket is no longer open.'])
     const sha = await resetToRunBranch()
     journal.append({

package/engine/core/execute.ts

@@ -32,7 +32,7 @@ import type { IntakeProblem } from '../intake/intake-schemas'
 import { jevAsksAfter, jevAsksBefore } from '../jev/jev-jobs'
 import { askJevInShadow, type JevShadow } from '../jev/jev-shadow'
 import type { Journal } from '../journal/journal'
-import type { JournalRecord } from '../journal/journal-record'
+import type { JournalRecord, LabelFailure } from '../journal/journal-record'
 import { replayRun } from '../journal/replay'
 import {
     crashesAfter,
@@ -178,6 +178,46 @@ const readIntake = async ({
     })
 }
 
+/**
+ * Moves a refused ticket from the ready label to needs-info. A label the
+ * tracker can't move doesn't stop the refusal (#500): each failure comes
+ * back, to be journaled.
+ */
+const moveToNeedsInfo = async ({
+    tracker,
+    ticket,
+}: {
+    tracker: Tracker
+    ticket: number
+}): Promise<LabelFailure[]> => {
+    const changes = [
+        { label: NEEDS_INFO_LABEL, change: 'add' },
+        { label: READY_LABEL, change: 'remove' },
+    ] as const
+    const failures: LabelFailure[] = []
+    for (const { label, change } of changes) {
+        try {
+            await (change === 'add' ? tracker.addLabel : tracker.removeLabel)({
+                number: ticket,
+                label,
+            })
+        } catch (error) {
+            failures.push({
+                ticket,
+                label,
+                change,
+                error: error instanceof Error ? error.message : String(error),
+            })
+        }
+    }
+    return failures
+}
+
+/**
+ * Refuses the run: each bad issue gets its comment (once, even on a redo
+ * after a crash) and moves to needs-info. The refusal is journaled even
+ * when a label couldn't move, so the run ends refused, not crashed.
+ */
 const refuseIntake = async ({
     spec_number,
     problems,
@@ -191,6 +231,7 @@ const refuseIntake = async ({
     tracker: Tracker
     step: CommentStep
 }) => {
+    const labelFailures: LabelFailure[] = []
     for (const [n, { ticket, missing }] of problems.entries()) {
         if (ticket === null) continue
         await postCommentOnce({
@@ -200,14 +241,13 @@ const refuseIntake = async ({
             step,
             n,
         })
-        await tracker.addLabel({ number: ticket, label: NEEDS_INFO_LABEL })
-        await tracker.removeLabel({ number: ticket, label: READY_LABEL })
+        labelFailures.push(...(await moveToNeedsInfo({ tracker, ticket })))
     }
     journal.append({
         kind: 'intake_refused',
         ticket: null,
         role: null,
-        content: { problems },
+        content: { problems, label_failures: labelFailures },
     })
 }
 
@@ -506,11 +546,12 @@ export const executeAction = async ({
                 content: {
                     closed_tickets: action.closed_tickets,
                     already_done: action.already_done,
+                    left_out: action.left_out ?? [],
                 },
             })
             return
         case 'snapshot_intake': {
-            const { spec, tickets, closed_tickets } = action.snapshot
+            const { spec, tickets, closed_tickets, left_out } = action.snapshot
             journal.append({
                 kind: 'spec_snapshot',
                 ticket: spec.number,
@@ -519,6 +560,7 @@ export const executeAction = async ({
                     spec,
                     ticket_order: tickets.map((ticket) => ticket.number),
                     closed_tickets,
+                    left_out,
                 },
             })
             for (const ticket of tickets) {