@alecsibilia/luca 14.0.0-alpha.1 → 14.0.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.2
+
+No changes in this release.
+
 ## 14.0.0-alpha.1
 
 ### Patch Changes

package/board/package.json

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

package/board/server/board-vocabulary.ts

@@ -128,7 +128,10 @@ export const BOARD_VOCABULARY = {
             })
         ),
     }),
-    nothing_to_do: z.looseObject({}),
+    /** The run ends with nothing to do; `already_done` is empty at intake (#484). */
+    nothing_to_do: z.looseObject({
+        already_done: z.array(z.number().int()).catch([]).default([]),
+    }),
     spec_snapshot: z.looseObject({
         spec: z.looseObject({ number: z.number(), title: z.string() }),
         ticket_order: z.array(z.number()).catch([]),
@@ -313,6 +316,12 @@ export const BOARD_VOCABULARY = {
     ticket_skipped: z.looseObject({
         because: z.number().int().nullable().catch(null),
     }),
+    /** A ticket whose work was already on the base branch (#484), done by `shas`. */
+    ticket_already_done: z.looseObject({
+        shas: z.array(z.string()).catch([]),
+    }),
+    /** The engine closed an already-done ticket, as the run opens no PR. */
+    ticket_closed: z.looseObject({}),
 
     // The final review (#367). Its agent, gate, scan, commit, and push
     // records are the usual kinds with `ticket: null`.
@@ -428,6 +437,8 @@ const BoardEntrySchema = z.discriminatedUnion('kind', [
     entry({ kind: 'reply_ignored' }),
     entry({ kind: 'ticket_retried' }),
     entry({ kind: 'ticket_skipped' }),
+    entry({ kind: 'ticket_already_done' }),
+    entry({ kind: 'ticket_closed' }),
     entry({ kind: 'final_review_started' }),
     entry({ kind: 'lens_started' }),
     entry({ kind: 'lens_finished' }),

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.1"
+export const LUCA_VERSION: string = "14.0.0-alpha.2"

package/board/server/make-rows.ts

@@ -11,6 +11,7 @@ import {
     runReasonText,
     reviewCountsText,
     roleWords,
+    shortSha,
     startKind,
 } from './reduce-board'
 
@@ -216,11 +217,16 @@ export const describeRecord = ({
                 text: `Intake refused the run. ${after.run.refusal.join('; ')}`,
                 tone: 'danger',
             })
-        case 'nothing_to_do':
+        case 'nothing_to_do': {
+            const done = record.content.already_done
             return event({
-                text: 'Nothing to do: the spec has no open tickets.',
+                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.`,
                 tone: 'info',
             })
+        }
         case 'spec_snapshot':
             return event({
                 text: `Intake passed: spec #${record.content.spec.number}, ${record.content.ticket_order.length} tickets.`,
@@ -389,6 +395,16 @@ export const describeRecord = ({
                 tone: 'info',
             })
         }
+        case 'ticket_already_done':
+            return event({
+                text: `${at}already done on the base branch, by ${record.content.shas.map((sha) => shortSha({ sha })).join(', ')}. Nothing to build.`,
+                tone: 'success',
+            })
+        case 'ticket_closed':
+            return event({
+                text: `${at}closed, since its work was already done.`,
+                tone: 'info',
+            })
         case 'ticket_skipped': {
             const { because } = record.content
             return event({
@@ -689,6 +705,12 @@ const finishedText = ({
         })
     }
     if (role === 'test-writer') {
+        if (result.outcome === 'already_done') {
+            return event({
+                text: `${at}the test-writer found the work already done.`,
+                tone: 'info',
+            })
+        }
         return result.outcome === 'nothing_new_to_test'
             ? event({ text: `${at}nothing new to test.`, tone: 'info' })
             : event({ text: `${at}tests written.`, tone: 'info' })

package/board/server/reduce-board.ts

@@ -40,7 +40,7 @@ const STUCK_REASONS: Record<string, string> = {
     agent_failed: 'An agent failed on its last try.',
     red_check_failed: 'The red check failed.',
     nothing_new_to_test:
-        'The test-writer found nothing new to test. If the ticket changes no behavior, label it refactor and start the run again.',
+        'The test-writer says the ticket changes no behavior, so there is nothing new to test. Label it refactor and retry it.',
     leftovers_found:
         'The leftover scan found files that must not be committed.',
     gates_failed: 'The checks failed.',
@@ -55,6 +55,24 @@ const STUCK_REASONS: Record<string, string> = {
     crashed: 'The engine crashed in the same step again and again.',
 }
 
+/**
+ * A commit's short sha, as git and GitHub show it.
+ *
+ * @example
+ * shortSha({ sha: '3559c25f5a1b' }) // '3559c25'
+ */
+export const shortSha = ({ sha }: { sha: string }): string => sha.slice(0, 7)
+
+/**
+ * An already-done ticket's activity (#484): calm, with the commits that
+ * did its work.
+ *
+ * @example
+ * alreadyDoneText({ shas: ['3559c25f5a1b'] }) // 'already done · 3559c25'
+ */
+export const alreadyDoneText = ({ shas }: { shas: string[] }): string =>
+    ['already done', ...shas.map((sha) => shortSha({ sha }))].join(' · ')
+
 /** Why a retry of an edited ticket was refused, in words. */
 export const RETRY_REFUSED_TEXT =
     "Its new text or labels aren't ready to build."
@@ -376,6 +394,8 @@ const STEP_WORDS: Record<string, string> = {
     push_final_fixes: 'pushing the run branch',
     write_changeset: 'writing the changeset',
     open_pull_request: 'opening the pull request',
+    mark_already_done: 'noting the work is already done',
+    close_ticket: 'closing the ticket',
 }
 
 /**
@@ -1275,6 +1295,23 @@ const applyKind = ({
                 ticket,
                 because: record.content.because,
             })
+        // Done, not stuck (#484): its work was already on the base branch.
+        case 'ticket_already_done':
+            return updateTicket({
+                state,
+                number: ticket,
+                update: (card) => ({
+                    ...card,
+                    stage: 'done',
+                    step: ALL_STEPS_DONE,
+                    role: null,
+                    open_check: null,
+                    activity: alreadyDoneText({ shas: record.content.shas }),
+                }),
+            })
+        // Its closing changes nothing the board shows.
+        case 'ticket_closed':
+            return state
         case 'ticket_retried':
             return ticketRetried({ state, record })
         // An ignored reply is only a chat row; the engine answered it.
@@ -1577,6 +1614,9 @@ const agentFinished = ({
                 if (card.open_check === 'review') {
                     return { ...done, activity: 'test findings answered' }
                 }
+                if (result.outcome === 'already_done') {
+                    return { ...done, activity: 'already done' }
+                }
                 return result.outcome === 'nothing_new_to_test'
                     ? { ...done, step: 2, activity: 'nothing new to test' }
                     : { ...done, step: 1, activity: 'red check' }

package/engine/agents/role-instructions.ts

@@ -82,8 +82,10 @@ You write the failing tests for ONE ticket, before any code exists.
 - Give every test a plain string-literal name (no test.each, no template names), so the engine can find each one before the module exists.
 
 Your result (structured output):
-- outcome: "tests_written", or "nothing_new_to_test" if the ticket truly changes no behavior (a refactor), or "needs_setup_change" if the tests can't work without a change to a test setup file${setupFiles({ config })} (you may never change one): say which file and why in "setup_change", and the user makes the change.
+- outcome: "tests_written", or "nothing_new_to_test" if the ticket truly changes no behavior (a refactor), or "already_done" if the ticket's work is already on the base branch, or "needs_setup_change" if the tests can't work without a change to a test setup file${setupFiles({ config })} (you may never change one): say which file and why in "setup_change", and the user makes the change.
+- Answer "already_done" only when EVERY acceptance criterion is already met on the base branch and already has a test that checks it. Look with \`git log\` and \`git show\`, and read the code and tests. Then write no tests, and give your evidence: in "done_by", the commits that did the work, as { sha, title }; in "criteria", the existing tests that cover each criterion. If even one criterion is not met, or not tested, write the tests instead.
 - criteria: for EACH criterion id (AC1, AC2, ...), the tests that check it, as { file, name }. "name" is the full name bun prints: describe names and the test name joined by " > ".
+- done_by: empty, unless the outcome is "already_done".
 - finding_responses: empty, unless your prompt gives you ticket review findings (see below).
 - summary, assumptions, run_notes.
 

package/engine/agents/role-results.ts

@@ -126,21 +126,39 @@ const SHARED_FIELDS = {
     run_notes: z.array(z.string()).default([]),
 }
 
+/** A commit on the base branch that did a ticket's work (#484). */
+export const DoneCommitSchema = z.object({
+    sha: z.string().min(1),
+    /** Its subject line, if the agent read it. */
+    title: z.string().default(''),
+})
+
+export type DoneCommit = z.infer<typeof DoneCommitSchema>
+
 /**
  * The test-writer's result. `nothing_new_to_test` is an honest answer for a
  * ticket that changes no behavior; the engine then makes the ticket stuck,
- * with a hint to label it `refactor`. `needs_setup_change` says the tests
- * can't be written without a change to a test setup file (`setup_change`),
- * which only the user may make.
+ * with a hint to label it `refactor`. `already_done` says the ticket's work
+ * is already on the base branch (#484): `done_by` names the commits that did
+ * it and `criteria` the existing tests that cover each criterion; the engine
+ * counts the ticket as done. `needs_setup_change` says the tests can't be
+ * written without a change to a test setup file (`setup_change`), which
+ * only the user may make.
  */
 export const TestWriterResultSchema = z.object({
     outcome: z.enum([
         'tests_written',
         'nothing_new_to_test',
+        'already_done',
         'needs_setup_change',
     ]),
-    /** For each criterion id (AC1, AC2, ...), the tests that check it. */
+    /**
+     * For each criterion id (AC1, AC2, ...), the tests that check it: new
+     * ones, or with `already_done`, the ones already on the base branch.
+     */
     criteria: z.array(CriterionTestsSchema).default([]),
+    /** With `already_done`: the base branch's commits that did the work. */
+    done_by: z.array(DoneCommitSchema).default([]),
     ...SETUP_FIELDS,
     ...SHARED_FIELDS,
     ...FIXER_FIELDS,
@@ -317,8 +335,24 @@ export const parseRoleResult = ({
             error: `The ${role}'s result does not fit its schema:\n${z.prettifyError(parsed.error)}`,
         }
     }
-    // Every reviewer (the ticket reviewer and each lens) gives a verdict.
     const { result } = parsed.data
+    // "Already done" is only an answer with its evidence (#484).
+    if (parsed.data.role === 'test-writer') {
+        const { outcome, done_by, criteria } = parsed.data.result
+        if (outcome === 'already_done' && done_by.length === 0) {
+            return {
+                ok: false,
+                error: 'The test-writer\'s "already_done" names no commit: list in "done_by" the base branch\'s commits that did the work.',
+            }
+        }
+        if (outcome === 'already_done' && criteria.length === 0) {
+            return {
+                ok: false,
+                error: 'The test-writer\'s "already_done" names no tests: list in "criteria" the existing tests that cover each criterion.',
+            }
+        }
+    }
+    // Every reviewer (the ticket reviewer and each lens) gives a verdict.
     if ('verdict' in result) {
         const { verdict, findings } = result
         const expected = findings.some(isBlocking)

package/engine/config/engine-config.ts

@@ -60,6 +60,11 @@ export const EngineConfigSchema = z.object({
      * that are gitignored, such as `bun run build:rom`. Agents never run it.
      */
     prepare: z.string().min(1).optional(),
+    /**
+     * How long the prepare command may run, in milliseconds; left out, the
+     * engine's default (`DEFAULT_PREPARE_TIMEOUT_MS`, 30 minutes).
+     */
+    prepare_timeout_ms: z.number().int().positive().optional(),
     test_file_patterns: z.array(z.string()).default(['**/*.test.ts']),
     test_setup_files: z.array(z.string()).default([]),
     rule_files: z.array(z.string()).default([]),
@@ -73,6 +78,26 @@ export const EngineConfigSchema = z.object({
 
 export type EngineConfig = z.infer<typeof EngineConfigSchema>
 
+/**
+ * How long the prepare command may run when the config doesn't say: 30
+ * minutes. A first build in a fresh worktree can take many minutes
+ * (HeartGold's takes about 8), far past the 5 minutes other commands get.
+ */
+export const DEFAULT_PREPARE_TIMEOUT_MS = 30 * 60 * 1000
+
+/**
+ * The prepare command's time limit: the config's `prepare_timeout_ms`, else
+ * the default.
+ *
+ * @example
+ * prepareTimeoutOf({ config: { ...config, prepare_timeout_ms: 3_600_000 } }) // 3_600_000
+ */
+export const prepareTimeoutOf = ({
+    config,
+}: {
+    config: EngineConfig
+}): number => config.prepare_timeout_ms ?? DEFAULT_PREPARE_TIMEOUT_MS
+
 /** One test command the engine runs, and how it reads the results. */
 export type TestCommand = { run: string; results: TestResults }
 

package/engine/core/already-done.ts

@@ -0,0 +1,139 @@
+import type {
+    CriterionTests,
+    DoneCommit,
+    TestWriterResult,
+} from '../agents/role-results'
+import type { TicketSnapshot } from '../intake/intake-schemas'
+
+/**
+ * A ticket whose work is already on the base branch (#484): its
+ * test-writer answered `already_done`, with the commits that did the work
+ * and the tests that already cover each criterion. The ticket is done, not
+ * stuck, and nobody has to reply. The run's PR closes it; a run with no PR
+ * closes it itself, and a run where every ticket was already done ends with
+ * nothing to do.
+ */
+export type AlreadyDoneAction =
+    /**
+     * Tell the spec issue (`body`) that the ticket's work is already done by
+     * `shas`, then journal the ticket as done.
+     */
+    | {
+          type: 'mark_already_done'
+          ticket: number
+          spec_number: number
+          shas: string[]
+          body: string
+      }
+    /** Close an already-done ticket, with `body` as a comment on it. */
+    | { type: 'close_ticket'; ticket: number; body: string }
+    /**
+     * 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.
+     */
+    | {
+          type: 'finish_nothing_to_do'
+          closed_tickets: number[]
+          already_done: number[]
+      }
+
+/** How many characters of a sha the engine shows. */
+const SHORT_SHA = 7
+
+/**
+ * A commit's short sha, as git and GitHub show it.
+ *
+ * @example
+ * shortSha({ sha: '3559c25f5a1b2c3d' }) // '3559c25'
+ */
+export const shortSha = ({ sha }: { sha: string }): string =>
+    sha.slice(0, SHORT_SHA)
+
+/** The commits in words: `3559c25`, or `3559c25 (feat: add sum)`. */
+const commitsText = ({ done_by }: { done_by: DoneCommit[] }): string =>
+    done_by
+        .map(({ sha, title }) =>
+            title === '' ? shortSha({ sha }) : `${shortSha({ sha })} (${title})`
+        )
+        .join(', ')
+
+const testsText = ({ criteria }: { criteria: CriterionTests[] }): string[] =>
+    criteria.flatMap(({ criterion_id, tests }) =>
+        tests.map(({ file, name }) => `- ${criterion_id}: ${file} > ${name}`)
+    )
+
+/**
+ * The step that marks a ticket already done, from its test-writer's
+ * `already_done`: the comment on the spec issue names the commits that
+ * did the work and the tests that cover each criterion, and says nobody
+ * has to reply.
+ *
+ * @example
+ * alreadyDoneStep({ spec_number: 10, base_branch: 'main', ticket, result })
+ * // { type: 'mark_already_done', ticket: 11, spec_number: 10, shas: ['3559c25f5...'], body: '**#11 is already done: Add sum** ...' }
+ */
+export const alreadyDoneStep = ({
+    spec_number,
+    base_branch,
+    ticket,
+    result,
+}: {
+    spec_number: number
+    base_branch: string
+    ticket: TicketSnapshot
+    result: TestWriterResult
+}): AlreadyDoneAction => {
+    const tests = testsText({ criteria: result.criteria })
+    const body = [
+        `**#${ticket.number} is already done: ${ticket.title}**`,
+        `The test-writer found this ticket's work already on \`${base_branch}\`, so this run builds nothing for it. It is done, not stuck: you don't need to reply.`,
+        `Done by: ${commitsText({ done_by: result.done_by })}`,
+        tests.length === 0
+            ? ''
+            : `Tests that already cover it:\n\n${tests.join('\n')}`,
+        result.summary === '' ? '' : `The test-writer says: ${result.summary}`,
+        "This run's PR closes it. If the run opens no PR, the engine closes it.",
+    ]
+    return {
+        type: 'mark_already_done',
+        ticket: ticket.number,
+        spec_number,
+        shas: result.done_by.map(({ sha }) => sha),
+        body: body.filter((part) => part !== '').join('\n\n'),
+    }
+}
+
+/**
+ * The step that closes an already-done ticket in a run with no PR, with a
+ * comment saying which commits did its work.
+ *
+ * @example
+ * closeTicketStep({ spec_number: 10, base_branch: 'main', ticket: 11, shas })
+ * // { type: 'close_ticket', ticket: 11, body: "Closing: this ticket's work is already on `main` ..." }
+ */
+export const closeTicketStep = ({
+    spec_number,
+    base_branch,
+    ticket,
+    shas,
+}: {
+    spec_number: number
+    base_branch: string
+    ticket: number
+    shas: string[]
+}): AlreadyDoneAction => ({
+    type: 'close_ticket',
+    ticket,
+    body:
+        `Closing: this ticket's work is already on \`${base_branch}\`, done by ${shas.map((sha) => shortSha({ sha })).join(', ')}. ` +
+        `Luca's run for spec #${spec_number} found nothing left to build for it, so it opens no PR for it.`,
+})
+
+/**
+ * An already-done ticket's line in the PR's ticket list, after its title.
+ *
+ * @example
+ * alreadyDoneNote({ shas: ['3559c25f5a1b'] }) // ' (already done before this run, by 3559c25)'
+ */
+export const alreadyDoneNote = ({ shas }: { shas: string[] }): string =>
+    ` (already done before this run, by ${shas.map((sha) => shortSha({ sha })).join(', ')})`