@alecsibilia/luca 14.0.0-alpha.5 → 14.0.0-alpha.6

package/CHANGELOG.md

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

package/board/package.json

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

package/board/server/board-vocabulary.ts

@@ -279,7 +279,10 @@ export const BOARD_VOCABULARY = {
         reason: z.string(),
         detail: z.string().catch(''),
     }),
-    /** The whole run is stuck (#435): `run_budget`, it used up its budget. */
+    /**
+     * The whole run is stuck (#435): `run_budget`, it used up its budget,
+     * or `pull_request_failed`, its PR didn't open (#508).
+     */
     run_stuck: z.looseObject({
         reason: z.string(),
         detail: z.string().catch(''),

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

package/board/server/reduce-board.ts

@@ -408,6 +408,8 @@ const resolveNeedsYou = ({
 const RUN_STUCK_REASONS: Record<string, string> = {
     run_budget:
         'The run used up its run budget of tokens. `retry` adds one more full budget.',
+    pull_request_failed:
+        "The run's pull request didn't open. `retry` tries again, reusing a PR already open from the run branch.",
 }
 
 /** A run stuck reason code in words. */

package/engine/agents/role-prompts.ts

@@ -190,6 +190,28 @@ export const prepareSection = ({ command }: { command: string }): string =>
             "If the engine's prepare command fails after your turn, its output comes back to you like a failed check.",
     ].join('\n\n')
 
+/**
+ * The section a test-writer or implementer (a ticket's or the final
+ * review's fixers) gets in a repo with changesets: the engine writes the
+ * run's one changeset, so an agent's own is extra.
+ */
+export const CHANGESETS_SECTION = [
+    '## The engine writes the changeset',
+    "Don't write changesets, even if the repo's rules ask for one: the engine writes the run's one changeset when it opens the PR. " +
+        'A new file you add in `.changeset/` is removed before the commit. ' +
+        'A finding that only asks for a changeset is answered by this: answer it "wont_fix" and say the engine adds it.',
+].join('\n\n')
+
+/**
+ * The section the rules lens gets in a repo with changesets, so a rule like
+ * "every PR needs a changeset" raises no finding.
+ */
+export const CHANGESETS_LENS_SECTION = [
+    '## The engine writes the changeset',
+    "The engine adds the run's one changeset when it opens the PR, so a rule that asks for a changeset is met. " +
+        'Raise no finding that only asks for a changeset.',
+].join('\n\n')
+
 /** What each lens judges the whole run branch on, in one paragraph. */
 const LENS_TASK_TEXT =
     'You are one lens of the final review: a fresh, read-only reviewer of the WHOLE run branch, every ticket of the spec together. Write nothing.'

package/engine/core/decide-build.ts

@@ -47,6 +47,8 @@ import {
 import { badTestDetail, retrySection, setupChangeDetail } from './stuck-text'
 
 import {
+    CHANGESETS_LENS_SECTION,
+    CHANGESETS_SECTION,
     prepareSection,
     rejoinSection,
     rolePrompt,
@@ -1303,34 +1305,47 @@ export const decideBuild = ({
 }): BuildAction[] => {
     const steps = buildSteps({ state, spec_number })
     const command = state.config?.prepare
-    return command === undefined
-        ? steps
-        : steps.map((step) => withPrepareSection({ step, command }))
+    const prepared =
+        command === undefined
+            ? steps
+            : steps.map((step) =>
+                  withWriterSection({
+                      step,
+                      section: prepareSection({ command }),
+                  })
+              )
+    return state.changesets ? prepared.map(withChangesetsSections) : prepared
 }
 
 /**
  * A fresh test-writer's or implementer's launch (a ticket's or the final
- * review's fixers), with the repo's prepare command named in its prompt.
- * Any other step as it is.
+ * review's fixers), with `section` added to its prompt, such as the repo's
+ * prepare command. Any other step as it is.
  */
-const withPrepareSection = ({
+const withWriterSection = ({
     step,
-    command,
+    section,
 }: {
     step: BuildAction
-    command: string
+    section: string
 }): BuildAction => {
     const writesCode =
         (step.type === 'launch_agent' || step.type === 'launch_final_fixer') &&
         (step.role === 'test-writer' || step.role === 'implementer')
     return writesCode
-        ? {
-              ...step,
-              prompt: `${step.prompt}\n\n${prepareSection({ command })}`,
-          }
+        ? { ...step, prompt: `${step.prompt}\n\n${section}` }
         : step
 }
 
+/**
+ * In a repo with changesets, the writers are told not to write one and the
+ * rules lens that the engine adds the run's one at PR time (#507).
+ */
+const withChangesetsSections = (step: BuildAction): BuildAction =>
+    step.type === 'launch_lens' && step.lens === 'rules'
+        ? { ...step, prompt: `${step.prompt}\n\n${CHANGESETS_LENS_SECTION}` }
+        : withWriterSection({ step, section: CHANGESETS_SECTION })
+
 /** `decideBuild`'s steps, before the prepare command joins any prompt. */
 const buildSteps = ({
     state,

package/engine/core/decide-run-budget.ts

@@ -1,5 +1,9 @@
 import { pendingReplies, waitForReply, type StuckAction } from './decide-stuck'
-import { runBudgetDetail, runStuckComment } from './stuck-text'
+import {
+    pullRequestStuckComment,
+    runBudgetDetail,
+    runStuckComment,
+} from './stuck-text'
 
 import type { JournalRecord, RunStuckReason } from '../journal/journal-record'
 import type { RunState } from '../journal/replay'
@@ -19,7 +23,9 @@ export type RunBudgetAction =
  * reason "run budget": that is its only step, and nothing new starts. The
  * spec issue is told, then the run waits for the owner: a bare `retry`
  * adds one more full budget (replay does that), and `stop` ends the run.
- * The owner's other replies wait until the run carries on. `null` when
+ * The owner's other replies wait until the run carries on. A run whose PR
+ * didn't open (#508) is stuck the same way, told why, and a `retry` tries
+ * the PR again, adding no budget. `null` when
  * the budget has nothing to say: the run is under it, stopping, or its PR
  * is open.
  *
@@ -56,7 +62,10 @@ export const decideRunBudget = ({
             {
                 type: 'report_run_stuck',
                 spec_number,
-                body: runStuckComment({ detail: stuck.detail, budget }),
+                body:
+                    stuck.reason === 'pull_request_failed'
+                        ? pullRequestStuckComment({ detail: stuck.detail })
+                        : runStuckComment({ detail: stuck.detail, budget }),
             },
         ]
     }

package/engine/core/execute-build.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { mkdir } from 'node:fs/promises'
+import { mkdir, rm } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 
 import difference from 'lodash/difference'
@@ -11,8 +11,6 @@ import { CHANGESET_CONFIG } from './changeset'
 import { mayEditTests, type BuildAction } from './decide-build'
 import type { FinalReviewAction } from './decide-final-review'
 import { retryTicket } from './execute-stuck'
-import { openTicketsNotInRun } from './not-in-run'
-import { withNotInRun } from './pull-request-text'
 import { closeSessions, openSessionsIn } from './session-close'
 
 import type { AgentLauncher, AgentTurn } from '../agents/agent-launcher'
@@ -25,7 +23,13 @@ import { bunTestCommands, type EngineConfig } from '../config/engine-config'
 import { checkAlreadyDone } from '../gates/already-done-check'
 import { prepareCheck, runGates, shellCheck } from '../gates/gate-runner'
 import { endedText } from '../gates/gate-schemas'
-import { newCodeFiles, importStem, scanLeftovers } from '../gates/leftover-scan'
+import {
+    importStem,
+    isAgentChangeset,
+    newCodeFiles,
+    scanLeftovers,
+    scratchNamedFiles,
+} from '../gates/leftover-scan'
 import {
     dependenciesChanged,
     installCommand,
@@ -450,6 +454,65 @@ const isUsed = async ({
     )
 }
 
+/**
+ * Whether a file other than itself and the tests names this scratch-named
+ * file by its basename, as a TOC, `package.json`, or a config does: a
+ * tracked file, or one this change adds (a new addon's TOC names its new
+ * modules). A mention in a test doesn't make a file the repo's.
+ */
+const isNamed = async ({
+    context,
+    cwd,
+    path,
+    added_texts,
+}: {
+    context: BuildContext
+    cwd: string
+    path: string
+    added_texts: Record<string, string>
+}): Promise<boolean> => {
+    const name = basename(path)
+    const tracked = await context.git.filesMentioning({ cwd, text: name })
+    const added = Object.entries(added_texts)
+        .filter(([, text]) => text.includes(name))
+        .map(([file]) => file)
+    const files = [...tracked, ...added].filter((file) => file !== path)
+    const tests = testFilesAmong({
+        files,
+        test_file_patterns: context.config.test_file_patterns,
+    })
+    return files.some((file) => !tests.includes(file))
+}
+
+/**
+ * In a repo with changesets, removes the changesets an agent wrote (see
+ * `isAgentChangeset`) from the worktree and journals `changeset_dropped`:
+ * the engine writes the run's one itself. Returns the other changes.
+ */
+export const dropAgentChangesets = async ({
+    context,
+    cwd,
+    ticket,
+    changes,
+}: {
+    context: BuildContext
+    cwd: string
+    ticket: number | null
+    changes: FileChange[]
+}): Promise<FileChange[]> => {
+    if (!context.state.changesets) return changes
+    const paths = changes.filter(isAgentChangeset).map(({ path }) => path)
+    if (paths.length === 0) return changes
+    for (const path of paths) await rm(join(cwd, path), { force: true })
+    context.journal.append({
+        kind: 'changeset_dropped',
+        ticket,
+        role: null,
+        content: { paths },
+    })
+    return changes.filter(({ path }) => !paths.includes(path))
+}
+
 /**
  * The commit a crash left behind at `cwd`: HEAD carries `message` and no
  * record names it yet, so the step's first try made it and died before
@@ -483,7 +546,8 @@ const leftCommit = async ({
  * The leftover scan, then an engine commit of everything in `cwd`, both
  * journaled. What the prepare command made (`prepare_made`) and untracked
  * links pointing outside the checkout (see `leaveOutIn`) are neither
- * scanned nor committed. A hit blocks the commit. A redo after a crash that
+ * scanned nor committed. An agent's changeset is dropped before the scan
+ * (see `dropAgentChangesets`). A hit blocks the commit. A redo after a crash that
  * already committed (nothing left to commit, and HEAD is an unjournaled
  * commit with this message) journals that commit instead of making
  * another; its scan, of a clean worktree, finds nothing, as the first try's
@@ -514,7 +578,12 @@ export const commitIn = async ({
     mention_text: string
 }) => {
     const leave_out = await leaveOutIn({ context, cwd, ticket })
-    const changes = await ticketChanges({ context, cwd, leave_out })
+    const changes = await dropAgentChangesets({
+        context,
+        cwd,
+        ticket,
+        changes: await ticketChanges({ context, cwd, leave_out }),
+    })
     const test_files = testFilesAmong({
         files: changes.map(({ path }) => path),
         test_file_patterns: context.config.test_file_patterns,
@@ -528,7 +597,19 @@ export const commitIn = async ({
     for (const path of newCodeFiles({ changes, test_files })) {
         used_code[path] = await isUsed({ context, cwd, path, added_texts })
     }
-    const hits = scanLeftovers({ changes, test_files, mention_text, used_code })
+    const named: string[] = []
+    for (const path of scratchNamedFiles({ changes })) {
+        if (await isNamed({ context, cwd, path, added_texts })) {
+            named.push(path)
+        }
+    }
+    const hits = scanLeftovers({
+        changes,
+        test_files,
+        mention_text,
+        used_code,
+        named,
+    })
     context.journal.append({
         kind: 'leftover_scan',
         ticket,
@@ -1151,12 +1232,15 @@ export const executeBuildAction = async ({
 }: BuildDeps & {
     /**
      * The final review's steps go to `executeFinalReviewAction`, the
-     * changeset to `writeChangeset`, and an already-done ticket's to
-     * `executeAlreadyDoneAction`.
+     * changeset to `writeChangeset`, the PR to `openPullRequest`, and an
+     * already-done ticket's to `executeAlreadyDoneAction`.
      */
     action: Exclude<
         BuildAction,
-        FinalReviewAction | AlreadyDoneAction | { type: 'write_changeset' }
+        | FinalReviewAction
+        | AlreadyDoneAction
+        | { type: 'write_changeset' }
+        | { type: 'open_pull_request' }
     >
     journal: Journal
     tracker: Tracker
@@ -1398,7 +1482,7 @@ export const executeBuildAction = async ({
         case 'report_final_review_stuck':
         case 'ship_final_review':
         case 'retry_final_review':
-            // Tracker-only steps; `executeAction` carries them out.
+            // Stuck work's steps; `executeAction` carries them out.
             throw new Error(`${action.type} is not a git or agent step.`)
         case 'mark_stuck':
             // A join crashes cut off too often leaves no half of it behind.
@@ -1418,36 +1502,6 @@ export const executeBuildAction = async ({
                 content: { reason: action.reason, detail: action.detail },
             })
             return
-        case 'open_pull_request': {
-            const { head, base, title, body } = action
-            // A redo adopts the PR its first try opened before the crash.
-            const adopted = context.step.redo
-                ? await tracker.findOpenPullRequest({ head })
-                : null
-            // The spec's open tickets not in the run are named in the PR.
-            const full = withNotInRun({
-                body,
-                open: await openTicketsNotInRun({
-                    tracker,
-                    state: context.state,
-                }),
-            })
-            const opened =
-                adopted ??
-                (await tracker.openPullRequest({
-                    head,
-                    base,
-                    title,
-                    body: full,
-                }))
-            journal.append({
-                kind: 'pull_request_opened',
-                ticket: null,
-                role: null,
-                content: { ...opened, head, base, title, body: full },
-            })
-            return
-        }
         case 'done':
         case 'invalid_journal':
             return

package/engine/core/execute-changeset.ts

@@ -12,7 +12,7 @@ import {
     type WorkspacePackage,
 } from './changeset'
 import type { BuildAction } from './decide-build'
-import { leaveOutIn, need, type BuildContext } from './execute-build'
+import { need, type BuildContext } from './execute-build'
 
 /** The part of the changesets config the engine reads: what it ignores. */
 const ChangesetConfigSchema = z
@@ -83,8 +83,9 @@ export const workspacePackages = async ({
 }
 
 /**
- * Writes the run's changeset on the run branch, commits it, and pushes the
- * run branch, then journals `changeset_written`. It names every workspace
+ * Writes the run's changeset on the run branch, commits it (only it: other
+ * uncommitted edits stay out, #509), and pushes the run branch, then
+ * journals `changeset_written`. It names every workspace
  * package with files changed since the run branch's base, minus the ones
  * the config ignores. A redo after a crash finds its own file already
  * committed and commits nothing twice. A `release:none` spec (#476), or a
@@ -145,11 +146,8 @@ export const writeChangeset = async ({
     await Bun.write(join(cwd, path), changesetText({ packages, bump, summary }))
     const changes = await git.changes({ cwd })
     if (changes.some((change) => change.path === path)) {
-        await git.commitAll({
-            cwd,
-            message,
-            leave_out: await leaveOutIn({ context, cwd, ticket: null }),
-        })
+        // Only the changeset: any other edit left in the worktree stays out.
+        await git.commitPaths({ cwd, message, paths: [path] })
     }
     await git.push({ cwd, branch })
     journal.append({

package/engine/core/execute-final-review.ts

@@ -4,15 +4,22 @@ import { isAbsolute, join } from 'node:path'
 import type { FinalReviewAction } from './decide-final-review'
 import {
     commitIn,
+    dropAgentChangesets,
     gatesIn,
+    leaveOutIn,
     need,
     runTurn,
     type BuildContext,
 } from './execute-build'
 import { closeSessions, openSessionsIn } from './session-close'
 
+import type { EngineCommit } from '../git/git-adapter'
 import type { Journal } from '../journal/journal'
-import { replayRun, type RuleFile } from '../journal/replay'
+import {
+    replayRun,
+    type FinalReviewState,
+    type RuleFile,
+} from '../journal/replay'
 
 /**
  * Carries out the final review's steps on the run branch's worktree: its
@@ -293,7 +300,8 @@ export const executeFinalReviewAction = async ({
 
 /**
  * The seam for replies (#366): when the person replies `ship` to a stuck
- * final review, the reply reader calls this. It journals
+ * final review, the reply reader calls this (the engine's ship step,
+ * `shipFinalReviewIn`, after committing any edits left over). It journals
  * `final_review_shipped`, and the next `runEngine` on the journal opens the
  * PR with the findings still open listed at the top of its description.
  * A final review that isn't stuck (or was already shipped) gets nothing.
@@ -304,21 +312,89 @@ export const executeFinalReviewAction = async ({
  */
 export const shipFinalReview = ({
     journal,
+    commit,
 }: {
     journal: Journal
+    /** The commit of the edits left uncommitted at ship time, if any. */
+    commit?: EngineCommit & { message: string }
 }): { ok: true } | { ok: false; reason: string } => {
-    const { final_review } = replayRun({ records: journal.read() })
-    if (final_review.stuck === null) {
-        return { ok: false, reason: 'The final review is not stuck.' }
-    }
-    if (final_review.shipped) {
-        return { ok: false, reason: 'The final review was already shipped.' }
-    }
+    const refused = shipRefusal({
+        final_review: replayRun({ records: journal.read() }).final_review,
+    })
+    if (refused !== null) return { ok: false, reason: refused }
     journal.append({
         kind: 'final_review_shipped',
         ticket: null,
         role: null,
-        content: {},
+        content: commit === undefined ? {} : { commit },
     })
     return { ok: true }
 }
+
+/** Why a final review can't be shipped, or `null` when it can. */
+const shipRefusal = ({
+    final_review,
+}: {
+    final_review: FinalReviewState
+}): string | null => {
+    if (final_review.stuck === null) return 'The final review is not stuck.'
+    if (final_review.shipped) return 'The final review was already shipped.'
+    return null
+}
+
+/**
+ * The commit message for the edits left uncommitted in the run branch's
+ * worktree when a stuck final review is shipped (#509).
+ *
+ * @example
+ * shippedEditsMessage({ round: 4 }) // 'fix: final review round 4, shipped with open findings'
+ */
+export const shippedEditsMessage = ({ round }: { round: number }): string =>
+    `fix: final review round ${round}, shipped with open findings`
+
+/**
+ * Carries out a `ship` reply to the stuck final review (#509): edits left
+ * uncommitted in the run branch's worktree (a fixer's, or the owner's) get
+ * their own commit (`shippedEditsMessage`), which is pushed, then
+ * `shipFinalReview` journals it with the ship, so the PR lists its files as
+ * not reviewed. What prepare made stays out, and a changeset a fixer wrote
+ * is dropped as at any engine commit (`dropAgentChangesets`), so the PR has
+ * only the engine's. With no edits, no commit. A redo after a crash that
+ * already committed adopts that commit.
+ */
+export const shipFinalReviewIn = async ({
+    context,
+}: {
+    context: BuildContext
+}): Promise<void> => {
+    const { journal, git, state } = context
+    const refused = shipRefusal({ final_review: state.final_review })
+    if (refused !== null) throw new Error(refused)
+    const { path: cwd, branch } = need({
+        value: state.run_branch,
+        what: 'run branch',
+    })
+    const message = shippedEditsMessage({ round: state.final_review.round })
+    const leave_out = await leaveOutIn({ context, cwd, ticket: null })
+    const changes = await dropAgentChangesets({
+        context,
+        cwd,
+        ticket: null,
+        changes: (await git.changes({ cwd })).filter(
+            ({ path }) => !leave_out.includes(path)
+        ),
+    })
+    let commit: (EngineCommit & { message: string }) | undefined
+    if (changes.length > 0) {
+        commit = {
+            ...(await git.commitAll({ cwd, message, leave_out })),
+            message,
+        }
+    } else if (context.step.redo) {
+        const last = await git.lastCommit({ cwd })
+        if (last.message === message) commit = last
+    }
+    if (commit !== undefined) await git.push({ cwd, branch })
+    const shipped = shipFinalReview({ journal, commit })
+    if (!shipped.ok) throw new Error(shipped.reason)
+}

package/engine/core/execute-pull-request.ts

@@ -0,0 +1,84 @@
+import { join } from 'node:path'
+
+import type { BuildAction } from './decide-build'
+import type { BuildContext } from './execute-build'
+import { openTicketsNotInRun } from './not-in-run'
+import {
+    fitPullRequestBody,
+    PULL_REQUEST_FILE,
+    withNotInRun,
+} from './pull-request-text'
+
+import { postCommentOnce } from '../tracker/post-comment-once'
+import { isTrackerFailure, type OpenedPullRequest } from '../tracker/tracker'
+
+const errorText = (error: unknown): string =>
+    error instanceof Error ? error.message : String(error)
+
+/**
+ * Opens the run's one pull request, then journals `pull_request_opened`
+ * (#508). Its full text (with the spec's open tickets not in the run) is
+ * saved first to `pull-request.md` in the run folder, so it's never lost.
+ * An open PR from the run branch is reused, never opened twice: the one a
+ * try opened before a crash or a failure, or one the owner opened by hand.
+ * The body sent keeps under `PULL_REQUEST_BUDGET`, and what doesn't fit
+ * is posted as PR comments after it (`fitPullRequestBody`), each once. A
+ * failed tracker call (`isTrackerFailure`: finding or opening the PR, such
+ * as a failed `gh pr create`) journals the run stuck (`pull_request_failed`)
+ * with its error, for the owner's `retry`; any other error is a crash.
+ */
+export const openPullRequest = async ({
+    context,
+    action,
+}: {
+    context: BuildContext
+    action: Extract<BuildAction, { type: 'open_pull_request' }>
+}): Promise<void> => {
+    const { journal, tracker, state, run_dir, step } = context
+    const { head, base, title, body } = action
+    // The spec's open tickets not in the run are named in the PR.
+    const full = withNotInRun({
+        body,
+        open: await openTicketsNotInRun({ tracker, state }),
+    })
+    await Bun.write(join(run_dir, PULL_REQUEST_FILE), full)
+    const fitted = fitPullRequestBody({ body: full })
+    let opened: OpenedPullRequest
+    try {
+        opened =
+            (await tracker.findOpenPullRequest({ head })) ??
+            (await tracker.openPullRequest({
+                head,
+                base,
+                title,
+                body: fitted.body,
+            }))
+    } catch (error) {
+        if (!isTrackerFailure(error)) throw error
+        journal.append({
+            kind: 'run_stuck',
+            ticket: null,
+            role: null,
+            content: {
+                reason: 'pull_request_failed',
+                detail: errorText(error),
+            },
+        })
+        return
+    }
+    for (const [n, comment] of fitted.comments.entries()) {
+        await postCommentOnce({
+            tracker,
+            number: opened.number,
+            body: comment,
+            step,
+            n,
+        })
+    }
+    journal.append({
+        kind: 'pull_request_opened',
+        ticket: null,
+        role: null,
+        content: { ...opened, head, base, title, body: full },
+    })
+}