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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.1
+
+### Patch Changes
+
+- 8a58510: Spec: Luca v14 fixes: no empty changesets, board version, init sets up the repo ([#480](https://github.com/asibilia/luca-framework/issues/480))
+
 ## 14.0.0-alpha.0
 
 ### Major Changes

package/README.md

@@ -24,17 +24,15 @@ This is Luca v14, in alpha. Old Luca (v13) is still on npm; see [Coming from v13
 
    While v14 is in alpha, npm's `latest` is still v13, so install `@alecsibilia/luca@alpha` for now.
 
-2. Set up this computer, once:
+2. Set up this computer and your repo, once, from inside your repo:
 
    ```bash
    luca init
    ```
 
-3. Set up your repo, once, from inside it:
+   Run inside a git repo, `luca init` sets up this computer, then runs `luca setup` to set up that repo too. Run outside a repo, it sets up only this computer. For another repo later, run `luca setup` from inside it.
 
-   ```bash
-   luca setup
-   ```
+3. Check what `luca setup` wrote to `.luca/config.json`. It names your repo's GitHub name (like `tmnb`) as its memory vault in `muninn.vault`; change it if you want another.
 
 4. In Claude Code, in your repo, run `/setup-matt-pocock-skills` so the planning skills know your repo.
 5. Write a spec with `/to-spec`, then split it into tickets with `/to-tickets`.
@@ -44,8 +42,8 @@ This is Luca v14, in alpha. Old Luca (v13) is still on npm; see [Coming from v13
 
 | Command | What it does |
 | ------- | ------------ |
-| `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, and the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`). It asks before turning on Paseo's plugins, and leaves skills you already have alone. `--skip-skills` skips the skills. |
-| `luca setup` | Gets the repo in this folder ready: the labels a run needs (and the `release:*` labels when the repo uses changesets), `.luca/config.json`, and a check of GitHub sub-issues and dependencies. `--base <branch>` names the base branch. |
+| `luca init` | Sets up this computer, once (safe to run again): MuninnDB and its Claude Code entry, the board in Paseo with its engine and Bun paths, and the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`). It asks before turning on Paseo's plugins, and leaves skills you already have alone. `--skip-skills` skips the skills. Inside a git repo, it then runs `luca setup` for that repo. |
+| `luca setup` | Gets the repo in this folder ready: the labels a run needs (and the `release:*` labels when the repo uses changesets), `.luca/config.json` (a new one gets the repo's GitHub name as its vault; an existing vault is kept), and a check of GitHub sub-issues and dependencies. `--base <branch>` names the base branch. |
 | `luca doctor` | Checks this computer, this repo when you're in one, and what v13 left behind. Each problem comes with its exact fix. `luca doctor --fix` fixes what's safe without asking: it never deletes (v13 files go to a dated backup folder) and never commits, and it lists the repo files to commit. |
 | `luca upgrade` | Moves to the newest Luca on your channel: `alpha` stays on `alpha`, and it never goes back to v13. It refuses while any run is going (stuck runs and limit waits count) and lists them. Then it reloads the board and says when to run `/reload-skills`. |
 | `luca upgrade --to <version>` | Installs that exact version, an older one too, to go back when a version breaks. |

package/board/index.server.ts

@@ -1,7 +1,5 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
 
 import type {
     PluginHandlerContext,
@@ -11,6 +9,7 @@ import type {
 import { createBoardServer } from './server/board-server'
 import { ENGINE_CHECK_MS } from './server/engine-watch'
 import { listProcesses } from './server/list-processes'
+import { LUCA_VERSION } from './server/luca-version'
 import { runCommand } from './server/run-command'
 import { defaultRunsDir } from './server/run-journals'
 import { defaultRegistryPath } from './server/run-registry'
@@ -37,29 +36,6 @@ type Paseo = PluginHandlerContext['paseo']
 
 const log = (message: string) => console.error(`[${PLUGIN_ID}] ${message}`)
 
-/**
- * The Luca version in the board folder's package.json, which the published
- * package stamps with its own version; `null` when it can't be read.
- */
-const loadedVersion = (): string | null => {
-    try {
-        const manifest: unknown = JSON.parse(
-            readFileSync(
-                join(dirname(fileURLToPath(import.meta.url)), 'package.json'),
-                'utf8'
-            )
-        )
-        return typeof manifest === 'object' &&
-            manifest !== null &&
-            'version' in manifest &&
-            typeof manifest.version === 'string'
-            ? manifest.version
-            : null
-    } catch {
-        return null
-    }
-}
-
 /**
  * The board plugin's daemon side: the engine settings (their usage lines
  * kept in a file for the engine), `run.start` (launch a
@@ -154,9 +130,8 @@ export default function contribute(server: PluginServerContext) {
         connect({ context })
         return board.readBoard(input)
     })
-    // Read once, as loaded: after an upgrade it differs until a reload.
-    const version = loadedVersion()
-    server.handle(boardVersionRpc, () => ({ version }))
+    // Fixed as loaded: after an upgrade it differs until a reload.
+    server.handle(boardVersionRpc, () => ({ version: LUCA_VERSION }))
 
     // Lifecycle hooks time out at 30 s, so the first check is not awaited.
     void board.checkEngines()

package/board/package.json

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

package/board/server/luca-version.ts

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

package/board/server/reduce-board.ts

@@ -49,6 +49,7 @@ const STUCK_REASONS: Record<string, string> = {
     join_failed: "The ticket couldn't join the run branch.",
     join_gates_failed: 'The checks failed after the ticket joined.',
     install_failed: 'Installing the dependencies failed.',
+    prepare_failed: "The repo's prepare command failed.",
     setup_change_needed:
         'An agent needs a test setup file changed; only you may change one.',
     crashed: 'The engine crashed in the same step again and again.',

package/board/shared/board-rpc.ts

@@ -117,8 +117,8 @@ export type BoardReadInput = z.input<typeof BoardReadInputSchema>
 export type BoardReadOutput = z.infer<typeof BoardReadOutputSchema>
 
 /**
- * API Response: the Luca version of the loaded board, read from its folder's
- * package.json when it was loaded; `null` when it has none.
+ * API Response: the Luca version of the loaded board, from its version
+ * module (the dev value from the repo's source); `null` from older boards.
  */
 export const BoardVersionOutputSchema = z.object({
     version: z.string().nullable(),

package/engine/agents/role-prompts.ts

@@ -109,6 +109,23 @@ export const runNotesSection = ({
                   .join('\n'),
           ]
 
+/**
+ * The section a test-writer or implementer gets when the repo has a prepare
+ * command: the engine runs it before its test runs, so tests that need its
+ * outputs may fail when the agent runs them itself.
+ *
+ * @example
+ * prepareSection({ command: 'bun run build:rom' })
+ * // '## This repo has a prepare command\n\n...'
+ */
+export const prepareSection = ({ command }: { command: string }): string =>
+    [
+        '## This repo has a prepare command',
+        `The engine runs \`${command}\` in the worktree before each of its test runs (the red check and the gates), so tests that need its outputs find them up to date. ` +
+            "Never run it yourself. Tests that need its outputs may fail when you run them, and still pass at the engine's checks. " +
+            "If the engine's prepare command fails after your turn, its output comes back to you like a failed check.",
+    ].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/cli/doctor-command.ts

@@ -24,25 +24,13 @@ import {
     paseoOf,
 } from './computer-adapters-real'
 import { runDoctor } from './doctor'
-import { githubOf, memoryOf } from './repo-adapters-real'
+import { githubOf, memoryOf, repoTop } from './repo-adapters-real'
 
 import type { MemoryClient } from '../memory/memory-client'
-import { runCommand } from '../shell/run-command'
 
 /** `luca doctor`'s usage line. */
 export const DOCTOR_USAGE = 'Usage: luca doctor [--fix]'
 
-/** The top of the git repo `cwd` is in, or `null` outside one. */
-const repoTop = async ({ cwd }: { cwd: string }): Promise<string | null> => {
-    const top = await runCommand({
-        cmd: ['git', 'rev-parse', '--show-toplevel'],
-        cwd,
-    })
-    return top.exit_code === 0 && top.stdout.trim() !== ''
-        ? top.stdout.trim()
-        : null
-}
-
 /** Runs `luca doctor` with the flags after `doctor`; returns the exit code. */
 export const doctorCommand = async ({
     argv,

package/engine/cli/init-command.ts

@@ -9,7 +9,8 @@
  * all of that: runs then have memory off. It puts the board into Paseo from
  * Luca's own install folder and writes its engine and Bun paths, asking
  * before it turns Paseo's plugins on. It installs the planning skills that
- * aren't there yet; `--skip-skills` skips them. See `runInit`.
+ * aren't there yet; `--skip-skills` skips them. Inside a git repo, it then
+ * runs `luca setup` for that repo. See `runInit`.
  *
  * Exits 0 when done, 1 when a step failed, 2 on bad flags.
  */
@@ -29,7 +30,9 @@ import {
 } from './computer-adapters-real'
 import { reason } from './doctor-checks'
 import { runInit, type Launchctl, type SkillsTool } from './init'
+import { githubOf, memoryOf, repoTop } from './repo-adapters-real'
 
+import type { MemoryClient } from '../memory/memory-client'
 import { runCommand } from '../shell/run-command'
 
 /** `luca init`'s flags. */
@@ -103,6 +106,24 @@ const skillsOf = ({ home }: { home: string }): SkillsTool => ({
     },
 })
 
+/**
+ * MuninnDB over MCP, found on first use: init writes Claude Code's `muninn`
+ * entry before its repo part reads it.
+ */
+const lazyMemory = (): MemoryClient => {
+    let client: Promise<MemoryClient> | null = null
+    const found = () => (client ??= memoryOf())
+    return {
+        recall: async (args) => (await found()).recall(args),
+        remember: async (args) => (await found()).remember(args),
+        evolve: async (args) => (await found()).evolve(args),
+        feedback: async (args) => (await found()).feedback(args),
+        close: async () => {
+            if (client !== null) await (await client).close()
+        },
+    }
+}
+
 /** Runs `luca init` with the flags after `init`; returns the exit code. */
 export const initCommand = async ({
     argv,
@@ -115,11 +136,21 @@ export const initCommand = async ({
     }
     const home = homedir()
     const paseo = paseoOf({ client_id: 'luca-init' })
+    const memory = lazyMemory()
     try {
+        const top = await repoTop({ cwd: process.cwd() })
         const end = await runInit({
             home,
             skip_muninndb: argv.includes('--skip-muninndb'),
             skip_skills: argv.includes('--skip-skills'),
+            repo:
+                top === null
+                    ? null
+                    : {
+                          path: top,
+                          github: await githubOf({ cwd: top }),
+                          memory,
+                      },
             muninn: muninnOf({ home }),
             muninn_health: muninnHealth,
             claude: claudeOf({ home }),
@@ -139,5 +170,6 @@ export const initCommand = async ({
         return 1
     } finally {
         await paseo.close()
+        await memory.close().catch(() => undefined)
     }
 }

package/engine/cli/init.ts

@@ -12,6 +12,7 @@ import type {
     Paseo,
 } from './computer-adapters'
 import { computerChecks } from './computer-checks'
+import type { DoctorRepo } from './doctor'
 import {
     formatChecks,
     hasProblem,
@@ -19,11 +20,12 @@ import {
     type DoctorCheck,
 } from './doctor-checks'
 import { ensureMuninnEntry, hideToken } from './muninn-entry'
+import { runSetup } from './setup'
 
 /**
  * `luca init`: sets up this computer for Luca, once, and is safe to run
  * again. It has three parts, each run even when an earlier one failed, and
- * ends with doctor's computer checks.
+ * ends with doctor's computer checks, then sets up the repo it runs in.
  *
  * Memory:
  *
@@ -48,6 +50,10 @@ import { ensureMuninnEntry, hideToken } from './muninn-entry'
  * `mattpocock/skills` with the `skills` tool, skipping any already there.
  * `skip_skills` skips this part.
  *
+ * The repo: inside a git repo, after the computer's checks, it runs `luca
+ * setup` for that repo (see `runSetup`), with the output setup gives on its
+ * own. Outside one, it stops after the computer part.
+ *
  * MuninnDB's CLI, `claude mcp`, `launchctl`, Paseo, the question to the
  * user, the `skills` tool, and the computer's tools are adapters, so tests
  * use fakes. The token is never printed, returned, or thrown.
@@ -258,17 +264,19 @@ const setUpMemory = async ({
 
 /**
  * Runs `luca init` against `home` with these adapters: memory, then the
- * board, then the planning skills, then doctor's computer checks, printed
- * last. Never throws: a failure is logged (token hidden) and ends with
- * `ok: false`, as does a check that is a problem.
+ * board, then the planning skills, then doctor's computer checks, then
+ * `luca setup` in `repo` when there is one. Never throws: a failure is
+ * logged (token hidden) and ends with `ok: false`, as does a check that is
+ * a problem or a setup to-do.
  *
  * @example
- * const end = await runInit({ home: homedir(), skip_muninndb: false, skip_skills: false, muninn, muninn_health, claude, launchctl, paseo, skills, ask, computer, ...(await lucaInstall()), log: console.log })
+ * const end = await runInit({ home: homedir(), skip_muninndb: false, skip_skills: false, repo: null, muninn, muninn_health, claude, launchctl, paseo, skills, ask, computer, ...(await lucaInstall()), log: console.log })
  */
 export const runInit = async ({
     home,
     skip_muninndb,
     skip_skills,
+    repo = null,
     muninn,
     muninn_health,
     claude,
@@ -286,6 +294,8 @@ export const runInit = async ({
     home: string
     skip_muninndb: boolean
     skip_skills: boolean
+    /** The git repo init runs in, set up after the computer; `null` outside one. */
+    repo?: DoctorRepo | null
     muninn: MuninnCli
     muninn_health: MuninnHealth
     claude: ClaudeMcp
@@ -333,12 +343,23 @@ export const runInit = async ({
         paseo,
     })
     for (const line of formatChecks({ checks: doctor })) log(line)
+    const setup =
+        repo === null
+            ? null
+            : await runSetup({
+                  repo: repo.path,
+                  github: repo.github,
+                  memory: repo.memory,
+                  base_branch: repo.base_branch,
+                  log,
+              })
     return {
         ok:
             memory.ok &&
             board.ok &&
             planning.ok &&
-            !hasProblem({ checks: doctor }),
+            !hasProblem({ checks: doctor }) &&
+            (setup?.ok ?? true),
         memory: memory.memory,
         message: planning.message,
         doctor,

package/engine/cli/luca.ts

@@ -3,7 +3,8 @@
  * `luca`: the command people run, with subcommands:
  *
  *   luca init [--skip-muninndb] [--skip-skills]
- *                                  sets up this computer, once
+ *                                  sets up this computer, once, then
+ *                                  the repo in this folder
  *   luca setup [--base <branch>]   gets the repo in this folder ready
  *   luca upgrade [--to <version>]  moves to another version of Luca
  *   luca doctor [--fix]            checks this computer and repo; --fix
@@ -22,7 +23,7 @@ const USAGE = `Usage: luca <command>
 
 Commands:
   init [--skip-muninndb] [--skip-skills]
-                            Set up this computer for Luca (once)
+                            Set up this computer for Luca (once), then the repo you're in
   setup [--base <branch>]   Get the repo in this folder ready for Luca
   upgrade [--to <version>]  Move to the newest Luca on your channel, or to <version>
   doctor [--fix]            Check this computer and repo; --fix fixes what's safe`

package/engine/cli/repo-adapters-real.ts

@@ -1,6 +1,7 @@
 /**
- * The real repo adapters `luca setup` and `luca doctor` share: the repo's
- * GitHub side, and MuninnDB over MCP for its vault.
+ * The real repo adapters `luca setup`, `luca init`, and `luca doctor`
+ * share: the repo's top folder, its GitHub side, and MuninnDB over MCP for
+ * its vault.
  */
 import type { SetupGitHub } from './setup'
 
@@ -10,12 +11,28 @@ import {
     createMuninnMcpClient,
     muninnSettings,
 } from '../memory/muninn-mcp-client'
+import { runCommand } from '../shell/run-command'
 import {
     createGitHubTracker,
     ghLogin,
     githubRepoOf,
 } from '../tracker/github-tracker'
 
+/** The top of the git repo `cwd` is in, or `null` outside one. */
+export const repoTop = async ({
+    cwd,
+}: {
+    cwd: string
+}): Promise<string | null> => {
+    const top = await runCommand({
+        cmd: ['git', 'rev-parse', '--show-toplevel'],
+        cwd,
+    })
+    return top.exit_code === 0 && top.stdout.trim() !== ''
+        ? top.stdout.trim()
+        : null
+}
+
 /**
  * The real GitHub side: the GitHub tracker of the repo at `cwd` for its
  * labels and issue links, and `gh` for the login. With no GitHub repo, the

package/engine/cli/setup.ts

@@ -35,7 +35,8 @@ import {
 /**
  * `luca setup`: gets a repo ready for Luca. It creates the labels a run
  * needs (and the `release:*` ones in a repo with changesets), writes a
- * starting `.luca/config.json` (or converts old Luca's, or leaves a
+ * starting `.luca/config.json` with the repo's GitHub name as its vault
+ * (or converts old Luca's, or leaves a
  * new-style one alone), runs `luca doctor`'s repo checks once, and ends
  * with a plain list of what's done and what's left, then a pointer to
  * `/setup-matt-pocock-skills`. It never commits, and running it again
@@ -262,6 +263,18 @@ const oldVault = ({ raw }: { raw: Record<string, unknown> }): string | null =>
     vaultName(isRecord(raw.muninn) ? raw.muninn.vault : undefined) ??
     vaultName(raw.vault)
 
+/**
+ * The `name` part of a GitHub `owner/name`, a new repo's vault. Pure.
+ *
+ * @example
+ * repoName({ github_repo: 'asibilia/tmnb' }) // 'tmnb'
+ */
+const repoName = ({
+    github_repo,
+}: {
+    github_repo: string | null
+}): string | null => vaultName(github_repo?.split('/').at(-1)?.trim() ?? null)
+
 const writeConfig = async ({
     repo,
     config,
@@ -591,7 +604,7 @@ const list = (lines: string[]): string =>
  * `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`), rewrites an old-Luca config into the new shape keeping
+ * `guessChecks`), with the repo's GitHub name as its `muninn.vault`, rewrites an old-Luca config into the new shape keeping
  * its `muninn.vault` (or an older top-level `vault`), and leaves a
  * new-style config alone; then checks the `gh` login and runs `luca
  * doctor`'s repo checks (`repoChecks`) once: the GitHub remote, sub-issues
@@ -640,7 +653,10 @@ export const runSetup = async ({
 
     const found = await findConfig({ repo })
     if (found.kind === 'missing' || found.kind === 'old') {
-        const vault = found.kind === 'old' ? oldVault({ raw: found.raw }) : null
+        const vault =
+            found.kind === 'old'
+                ? oldVault({ raw: found.raw })
+                : repoName({ github_repo })
         await writeConfig({
             repo,
             config: startingConfig({
@@ -653,6 +669,11 @@ export const runSetup = async ({
                 ? `Wrote ${ENGINE_CONFIG_FILE} from package.json's scripts. Check it, then merge it to main through a PR.`
                 : `Rewrote old Luca's ${ENGINE_CONFIG_FILE} into the new shape${vault === null ? '' : `, keeping the \`${vault}\` vault`}. Check it, then merge it to main through a PR.`
         )
+        if (found.kind === 'missing' && vault !== null) {
+            done_lines.push(
+                `Set the memory vault to \`${vault}\`, the repo's GitHub name. Change \`muninn.vault\` in ${ENGINE_CONFIG_FILE} to use another.`
+            )
+        }
     } else if (found.kind === 'new') {
         done_lines.push(
             `${ENGINE_CONFIG_FILE} is new-style, so it was left as it is`

package/engine/config/engine-config.ts

@@ -54,6 +54,12 @@ export const EngineConfigSchema = z.object({
             lint: z.string().min(1).optional(),
         })
         .default({}),
+    /**
+     * A command the engine runs in a checkout before every test run there
+     * (baseline, red check, gates), for repos whose tests need build outputs
+     * that are gitignored, such as `bun run build:rom`. Agents never run it.
+     */
+    prepare: z.string().min(1).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([]),

package/engine/core/changeset.ts

@@ -116,8 +116,8 @@ export const changedPackages = ({
 
 /**
  * A changeset's text: front matter naming each package with the bump, then
- * the summary. `release:none` (or no package) gives empty front matter, a
- * changeset that bumps nothing.
+ * the summary. `release:none` gets no changeset at all (#476), so it has no
+ * text.
  *
  * @example
  * changesetText({ packages: ['@acme/a'], bump: 'minor', summary: 'Add a' })
@@ -129,12 +129,11 @@ export const changesetText = ({
     summary,
 }: {
     packages: string[]
-    bump: ChangesetBump
+    bump: Exclude<ChangesetBump, 'none'>
     summary: string
 }): string => {
-    const releases =
-        bump === 'none'
-            ? []
-            : packages.map((name) => `${JSON.stringify(name)}: ${bump}\n`)
+    const releases = packages.map(
+        (name) => `${JSON.stringify(name)}: ${bump}\n`
+    )
     return `---\n${releases.join('')}---\n\n${summary}\n`
 }

package/engine/core/decide-build.ts

@@ -37,7 +37,11 @@ import {
 } from './review-text'
 import { retrySection, setupChangeDetail } from './stuck-text'
 
-import { rejoinSection, rolePrompt } from '../agents/role-prompts'
+import {
+    prepareSection,
+    rejoinSection,
+    rolePrompt,
+} from '../agents/role-prompts'
 import type { AgentRole, CriterionTests } from '../agents/role-results'
 import type { TicketSnapshot } from '../intake/intake-schemas'
 import type {
@@ -970,6 +974,14 @@ const nextTicketStep = ({
             detail: ticketFailure,
         })
     }
+    const { prepare } = progress
+    if (prepare !== null && !prepare.ok) {
+        return stuck({
+            ticket: number,
+            reason: 'prepare_failed',
+            detail: `\`${prepare.command}\` failed in the worktree of #${number} (exit ${prepare.exit_code ?? 'none'}) before any agent worked on it. Agents never run the prepare command, so fix what it needs (a missing tool, say) and retry.\n${prepare.output}`,
+        })
+    }
     if (progress.baseline === null) return baseline_step
     if (progress.commits.green === null) {
         const rejoin = rejoinStep({
@@ -1058,6 +1070,44 @@ export const decideBuild = ({
 }: {
     state: RunState
     spec_number: number
+}): BuildAction[] => {
+    const steps = buildSteps({ state, spec_number })
+    const command = state.config?.prepare
+    return command === undefined
+        ? steps
+        : steps.map((step) => withPrepareSection({ step, command }))
+}
+
+/**
+ * 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.
+ */
+const withPrepareSection = ({
+    step,
+    command,
+}: {
+    step: BuildAction
+    command: 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
+}
+
+/** `decideBuild`'s steps, before the prepare command joins any prompt. */
+const buildSteps = ({
+    state,
+    spec_number,
+}: {
+    state: RunState
+    spec_number: number
 }): BuildAction[] => {
     const { snapshot, run_branch, run_branch_install, pull_request } = state
     const base_branch = state.base_branch ?? 'main'

package/engine/core/execute-build.ts

@@ -17,7 +17,7 @@ import {
     type RoleResult,
 } from '../agents/role-results'
 import { bunTestCommands, type EngineConfig } from '../config/engine-config'
-import { runGates, shellCheck } from '../gates/gate-runner'
+import { prepareCheck, runGates, shellCheck } from '../gates/gate-runner'
 import { newCodeFiles, importStem, scanLeftovers } from '../gates/leftover-scan'
 import {
     dependenciesChanged,
@@ -155,6 +155,7 @@ const runRedCheck = async ({
         what: `baseline test run for #${action.ticket}`,
     })
     const test_files = await testFilesIn({ context, cwd: path })
+    const prepare = await prepareCheck({ config: context.config, cwd: path })
     const current = await runBunTests({
         cwd: path,
         commands: bunTestCommands(context),
@@ -170,7 +171,7 @@ const runRedCheck = async ({
     )
     const sources: Record<string, string | null> = {}
     for (const file of files) sources[file] = await readOrNull(join(path, file))
-    const result = checkRed({
+    const checked = checkRed({
         criteria_ids: action.criteria_ids,
         mapping: action.mapping,
         baseline,
@@ -178,6 +179,19 @@ const runRedCheck = async ({
         test_files,
         sources,
     })
+    // A failed prepare after the test-writer's turn is one more problem,
+    // for the test-writer's fix loop.
+    const result =
+        prepare === null || prepare.ok
+            ? checked
+            : {
+                  ...checked,
+                  ok: false,
+                  problems: [
+                      `The prepare command \`${prepare.command}\` failed (exit ${prepare.exit_code ?? 'none'}):\n${prepare.output}`,
+                      ...checked.problems,
+                  ],
+              }
     context.journal.append({
         kind: 'red_check',
         ticket: action.ticket,
@@ -935,6 +949,21 @@ export const executeBuildAction = async ({
         }
         case 'run_baseline_tests': {
             const { path } = ticketWorktree({ state, ticket: action.ticket })
+            const prepare = await prepareCheck({
+                config: context.config,
+                cwd: path,
+            })
+            if (prepare !== null) {
+                journal.append({
+                    kind: 'baseline_prepared',
+                    ticket: action.ticket,
+                    role: null,
+                    content: { check: prepare },
+                })
+                // No agent has worked yet, so a failed prepare leaves the
+                // tests unrun and the ticket stuck on its output.
+                if (!prepare.ok) return
+            }
             const run = await runBunTests({
                 cwd: path,
                 commands: bunTestCommands(context),

package/engine/core/execute-changeset.ts

@@ -86,9 +86,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
  * package with files changed since the run branch's base, minus the ones
- * the config ignores; `release:none` names none. A redo after a crash finds
- * its own file already committed and commits nothing twice. A repo whose
- * config is gone by now gets no changeset.
+ * 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
+ * repo whose config is gone by now, gets no changeset.
  */
 export const writeChangeset = async ({
     context,
@@ -118,21 +118,29 @@ export const writeChangeset = async ({
         })
         return
     }
+    if (bump === 'none') {
+        await git.push({ cwd, branch })
+        journal.append({
+            kind: 'changeset_written',
+            ticket: null,
+            role: null,
+            content: {
+                path: null,
+                bump,
+                packages: [],
+                sha: await git.head({ cwd }),
+            },
+        })
+        return
+    }
     const { ignore } = ChangesetConfigSchema.parse(
         await readJson(join(cwd, CHANGESET_CONFIG))
     )
-    const packages =
-        bump === 'none'
-            ? []
-            : changedPackages({
-                  packages: await workspacePackages({ cwd }),
-                  files: await git.filesBetween({
-                      cwd,
-                      from: base_sha,
-                      to: 'HEAD',
-                  }),
-                  ignore,
-              })
+    const packages = changedPackages({
+        packages: await workspacePackages({ cwd }),
+        files: await git.filesBetween({ cwd, from: base_sha, to: 'HEAD' }),
+        ignore,
+    })
     const path = changesetPath({ spec_number, run_id: basename(run_dir) })
     await Bun.write(join(cwd, path), changesetText({ packages, bump, summary }))
     const changes = await git.changes({ cwd })

package/engine/core/stuck-text.ts

@@ -30,6 +30,8 @@ const REASON_LINES: Record<StuckReason, string> = {
     join_gates_failed:
         'The checks still fail once the ticket joins the run branch.',
     install_failed: 'Installing the dependencies failed.',
+    prepare_failed:
+        "The repo's prepare command failed before any agent worked.",
     setup_change_needed:
         'An agent needs a test setup file changed, and only you may change one.',
     crashed: 'The engine crashed in the same step, again and again.',
@@ -65,6 +67,8 @@ const suggestion = ({
             return `Its join was undone, so the run branch is safe. Reply ${retry} to join again and fix it on top of the run branch, or \`skip #${n}\`.`
         case 'install_failed':
             return `Fix the manifest or lockfile on the base branch, then reply ${retry}.`
+        case 'prepare_failed':
+            return `Fix what the prepare command needs on this computer (a missing tool, say), or the command in \`.luca/config.json\`, then reply ${retry}.`
         case 'setup_change_needed':
             return `Make that change yourself in the worktree, then reply ${retry}.`
         case 'crashed':

package/engine/gates/gate-runner.ts

@@ -33,6 +33,26 @@ export const shellCheck = async ({
     }
 }
 
+/**
+ * Runs the config's prepare command in `cwd`, as the `prepare` check, or
+ * `null` when the config has none. The engine runs it before every test run
+ * in a checkout, so tests that need build outputs find them up to date.
+ *
+ * @example
+ * const prepare = await prepareCheck({ config, cwd })
+ * if (prepare !== null && !prepare.ok) console.log(prepare.output)
+ */
+export const prepareCheck = async ({
+    config,
+    cwd,
+}: {
+    config: EngineConfig
+    cwd: string
+}): Promise<GateCheck | null> =>
+    config.prepare === undefined
+        ? null
+        : shellCheck({ name: 'prepare', command: config.prepare, cwd })
+
 /**
  * Runs every gate the engine config names, in order: each test command,
  * types, lint. All must pass. Unset gates are left out; intake refuses a
@@ -41,7 +61,8 @@ export const shellCheck = async ({
  *
  * With an `install` command (see `installCommand`), the engine runs it first,
  * as the `install` check. A failed install stops there: the other gates
- * would only fail on the missing packages.
+ * would only fail on the missing packages. The config's prepare command
+ * runs next, as the `prepare` check, and a failed one stops there too.
  *
  * @example
  * const { ok, checks } = await runGates({ cwd, config, test_files, report_file, install: null })
@@ -69,6 +90,11 @@ export const runGates = async ({
         checks.push(installed)
         if (!installed.ok) return { ok: false, checks }
     }
+    const prepared = await prepareCheck({ config, cwd })
+    if (prepared !== null) {
+        checks.push(prepared)
+        if (!prepared.ok) return { ok: false, checks }
+    }
     const { types, lint } = config.checks
     for (const [index, { run: command, results }] of testCommands({
         config,

package/engine/gates/gate-schemas.ts

@@ -28,9 +28,16 @@ export type TestRun = z.infer<typeof TestRunSchema>
 
 /**
  * The gates the engine config can name, plus `install`: the engine's own
- * install, run first when a package manifest changed.
+ * install, run first when a package manifest changed, and `prepare`: the
+ * config's prepare command, run before the tests.
  */
-export const GateNameSchema = z.enum(['install', 'test', 'types', 'lint'])
+export const GateNameSchema = z.enum([
+    'install',
+    'prepare',
+    'test',
+    'types',
+    'lint',
+])
 
 export type GateName = z.infer<typeof GateNameSchema>
 

package/engine/journal/journal-record.ts

@@ -151,6 +151,17 @@ const TicketWorktreeCreatedEntrySchema = z.object({
     content: WorktreeSchema,
 })
 
+/**
+ * The config's prepare command (#481), run in a new ticket worktree before
+ * its baseline tests. Journaled only with a prepare command. A failed one
+ * leaves the baseline tests unrun.
+ */
+const BaselinePreparedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('baseline_prepared'),
+    content: z.object({ check: GateCheckSchema }),
+})
+
 /** The tests as they stood before any agent worked on a ticket. */
 const BaselineTestsEntrySchema = z.object({
     ...ENTRY_FIELDS,
@@ -597,6 +608,7 @@ export const StuckReasonSchema = z.enum([
     'join_failed',
     'join_gates_failed',
     'install_failed',
+    'prepare_failed',
     'setup_change_needed',
     'crashed',
 ])
@@ -772,8 +784,9 @@ export type ChangesetBump = z.infer<typeof ChangesetBumpSchema>
 /**
  * The engine committed the run's one changeset (#461) at `path` on the run
  * branch and pushed it (`sha` is the run branch's HEAD after). `packages`
- * are the ones it names (none for `release:none`). `path` is `null` when
- * the repo no longer had a changesets config, so nothing was written.
+ * are the ones it names. `path` is `null` when nothing was written: the
+ * spec is `release:none` (#476), or the repo no longer had a changesets
+ * config.
  */
 const ChangesetWrittenEntrySchema = z.object({
     ...ENTRY_FIELDS,
@@ -1111,6 +1124,7 @@ export const JournalEntrySchema = z.discriminatedUnion('kind', [
     TicketSnapshotEntrySchema,
     RunBranchCreatedEntrySchema,
     TicketWorktreeCreatedEntrySchema,
+    BaselinePreparedEntrySchema,
     BaselineTestsEntrySchema,
     BaselineReusedEntrySchema,
     AgentStartedEntrySchema,
@@ -1185,6 +1199,7 @@ export const JournalRecordSchema = z.discriminatedUnion('kind', [
     TicketSnapshotEntrySchema.extend(STAMP_FIELDS),
     RunBranchCreatedEntrySchema.extend(STAMP_FIELDS),
     TicketWorktreeCreatedEntrySchema.extend(STAMP_FIELDS),
+    BaselinePreparedEntrySchema.extend(STAMP_FIELDS),
     BaselineTestsEntrySchema.extend(STAMP_FIELDS),
     BaselineReusedEntrySchema.extend(STAMP_FIELDS),
     AgentStartedEntrySchema.extend(STAMP_FIELDS),
@@ -1258,6 +1273,7 @@ export const JournalKindSchema = z.enum([
     'ticket_snapshot',
     'run_branch_created',
     'ticket_worktree_created',
+    'baseline_prepared',
     'baseline_tests',
     'baseline_reused',
     'agent_started',

package/engine/journal/replay.ts

@@ -139,6 +139,8 @@ export type TicketProgress = {
     worktree: ReplayedWorktree | null
     /** The install in the new worktree; its `check` is `null` with no manifest. */
     install: ReplayedInstall | null
+    /** The prepare command run before its baseline tests (`baseline_prepared`). */
+    prepare: GateCheck | null
     /** Its own baseline test run, or the one it reused (`baseline_reused`). */
     baseline: TestRun | null
     /**
@@ -531,6 +533,7 @@ export type RunState = {
 export const EMPTY_TICKET_PROGRESS: TicketProgress = {
     worktree: null,
     install: null,
+    prepare: null,
     baseline: null,
     baseline_sha: null,
     test_writer: null,
@@ -1820,6 +1823,8 @@ const progressChange = ({
             return { worktree: record.content }
         case 'dependencies_installed':
             return { install: { check: record.content.check } }
+        case 'baseline_prepared':
+            return { prepare: record.content.check }
         case 'baseline_tests':
             return {
                 baseline: record.content,
@@ -2092,8 +2097,9 @@ const retriedChange = ({
  *   branch after a rebase), then the gates;
  * - in a review fix round, the round starts over as round 1 with fresh
  *   fixers, so the user's changes are gated, committed, and re-reviewed;
- * - a leftover scan, a failed install, a reviewer's failed tries, a
- *   failed join, or a step crashes cut off just run again.
+ * - a leftover scan, a failed install, a failed prepare command at the
+ *   baseline, a reviewer's failed tries, a failed join, or a step crashes
+ *   cut off just run again.
  */
 const resumedProgress = ({
     progress,
@@ -2117,6 +2123,7 @@ const resumedProgress = ({
         rejoins: 0,
         install:
             progress.install?.check?.ok === false ? null : progress.install,
+        prepare: progress.prepare?.ok === false ? null : progress.prepare,
         leftovers: {
             red: commits.red === null ? null : progress.leftovers.red,
             green: commits.green === null ? null : progress.leftovers.green,
@@ -2128,6 +2135,7 @@ const resumedProgress = ({
     if (
         reason === 'leftovers_found' ||
         reason === 'install_failed' ||
+        reason === 'prepare_failed' ||
         reason === 'join_failed' ||
         reason === 'join_gates_failed' ||
         reason === 'crashed' ||

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@alecsibilia/luca",
     "description": "Luca: turns a spec on GitHub Issues into a reviewed pull request, run from Paseo with Claude Code",
-    "version": "14.0.0-alpha.0",
+    "version": "14.0.0-alpha.1",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",