@alecsibilia/luca 14.0.0-alpha.13 → 14.0.0-alpha.14

package/CHANGELOG.md

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

package/board/client/board-look.ts

@@ -73,7 +73,11 @@ export const stageColor = ({
     switch (stage) {
         case 'building':
         case 'reviewing':
+        case 'testing':
+        case 'joining':
             return theme.colors.accent
+        case 'fixing':
+            return theme.colors.statusWarning
         case 'stuck':
             return theme.colors.statusDanger
         case 'done':

package/board/client/board-panel.tsx

@@ -55,8 +55,9 @@ import { postedText, type PostedReply } from '../shared/reply-actions'
 /**
  * The side panel: one run of this workspace, top to bottom. Plan usage, a
  * limit-wait banner, "Needs you" pinned on top, the tickets as a stack of
- * stages (Blocked → Building → Reviewing → Done → Skipped) with step dots,
- * then the final review's 5 lenses as a second stack. It polls `board.read`.
+ * stages (Blocked → Building → Reviewing → Testing → Fixing → Joining → Done
+ * → Skipped) with step dots, then the final review's 5 lenses as a second
+ * stack. It polls `board.read`.
  */
 
 type StackStage = Exclude<TicketStage, 'stuck'>
@@ -78,17 +79,38 @@ const TICKET_STAGES: {
     {
         stage: 'building',
         title: 'Building',
-        hint: 'tests, red check, code, checks',
+        hint: 'the first tests and code',
         icon: 'Hammer',
         folded: false,
     },
     {
         stage: 'reviewing',
         title: 'Reviewing',
-        hint: 'a fresh ticket review and its fix rounds',
+        hint: 'a reviewer reads the ticket',
         icon: 'ScanSearch',
         folded: false,
     },
+    {
+        stage: 'testing',
+        title: 'Testing',
+        hint: 'the red check or the checks running',
+        icon: 'FlaskConical',
+        folded: false,
+    },
+    {
+        stage: 'fixing',
+        title: 'Fixing',
+        hint: 'a fix round after the checks, a review or a join',
+        icon: 'Wrench',
+        folded: false,
+    },
+    {
+        stage: 'joining',
+        title: 'Joining',
+        hint: 'joining the run branch and its checks there',
+        icon: 'GitMerge',
+        folded: false,
+    },
     {
         stage: 'done',
         title: 'Done',

package/board/package.json

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

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

package/board/server/reduce-board.ts

@@ -21,6 +21,7 @@ import {
     type RunInfo,
     type RunStatus,
     type TicketCard,
+    type TicketStage,
     type Usage,
 } from '../shared/board-state'
 import {
@@ -494,9 +495,40 @@ const withoutSteps = ({ state }: { state: BoardState }): BoardState =>
         run_steps: [],
     })
 
+/** The stages a step doesn't move a ticket out of. */
+const SETTLED_STAGES = new Set<TicketStage>(['stuck', 'done', 'skipped'])
+
 /**
- * A step began: it is its ticket's current step, or one of the run's.
- * A new step on the same key (a crash's redo) replaces the one before it.
+ * The stage a ticket's step puts it in (#549): the red check and the checks
+ * are testing, but the checks after joining are still joining; joining and
+ * pushing the run branch are joining. Any other step, or a stuck, done or
+ * skipped ticket, keeps its stage.
+ */
+const stepStage = ({
+    card,
+    step,
+}: {
+    card: TicketCard
+    step: string
+}): TicketStage => {
+    if (SETTLED_STAGES.has(card.stage)) return card.stage
+    switch (step) {
+        case 'run_red_check':
+            return 'testing'
+        case 'run_gates':
+            return card.stage === 'joining' ? 'joining' : 'testing'
+        case 'join_run_branch':
+        case 'push_run_branch':
+            return 'joining'
+        default:
+            return card.stage
+    }
+}
+
+/**
+ * A step began: it is its ticket's current step, or one of the run's, and
+ * it sets the ticket's stage. A new step on the same key (a crash's redo)
+ * replaces the one before it.
  */
 const stepStarted = ({
     state,
@@ -506,7 +538,7 @@ const stepStarted = ({
     record: Extract<BoardRecord, { kind: 'step_started' }>
 }): BoardState => {
     // A replayed journal of an engine that ended has no step running.
-    if (state.run.engine_ended !== null) return state
+    const ended = state.run.engine_ended !== null
     const current_step = {
         text: stepText({ step: record.content.step }),
         since: record.time,
@@ -515,9 +547,14 @@ const stepStarted = ({
         return updateTicket({
             state,
             number: record.ticket,
-            update: (card) => ({ ...card, current_step }),
+            update: (card) => ({
+                ...card,
+                stage: stepStage({ card, step: record.content.step }),
+                current_step: ended ? card.current_step : current_step,
+            }),
         })
     }
+    if (ended) return state
     const { key } = record.content
     return withRunSteps({
         state,
@@ -1096,6 +1133,7 @@ const applyKind = ({
                 number: ticket,
                 update: (card) => ({
                     ...card,
+                    stage: 'building',
                     step: 0,
                     fix_round: 0,
                     open_check: null,
@@ -1177,11 +1215,13 @@ const applyKind = ({
             return updateTicket({
                 state,
                 number: ticket,
+                // Joined, it is done once its checks there pass and the run
+                // branch is pushed.
                 update: (card) =>
                     record.content.ok
                         ? {
                               ...card,
-                              stage: 'done',
+                              stage: 'joining',
                               step: ALL_STEPS_DONE,
                               role: null,
                               activity: 'joined',
@@ -1203,6 +1243,7 @@ const applyKind = ({
                 number: ticket,
                 update: (card) => ({
                     ...card,
+                    stage: 'fixing',
                     step: 0,
                     role: null,
                     activity: 'updating tests for the run branch',
@@ -1217,8 +1258,8 @@ const applyKind = ({
                 state,
                 number: ticket,
                 update: (card) =>
-                    card.stage === 'done'
-                        ? { ...card, activity: 'pushed' }
+                    card.stage === 'joining' || card.stage === 'done'
+                        ? { ...card, stage: 'done', activity: 'pushed' }
                         : card,
             })
         case 'ticket_stuck': {
@@ -1553,7 +1594,7 @@ const OPEN_CHECK_TEXT = {
 /**
  * A fixer's start in a review fix round. The round is the review's round (a
  * round follows each review that asked for changes); only the round's first
- * fixer adds its "tried" line. The card stays in Reviewing at its step.
+ * fixer adds its "tried" line. The card is fixing, at its step.
  */
 const reviewFixStarted = ({
     card,
@@ -1570,7 +1611,7 @@ const reviewFixStarted = ({
         ...card,
         started: true,
         role,
-        stage: 'reviewing',
+        stage: 'fixing',
         review_fix_round: round,
         activity: `fixing the review's findings (${round}/${LOOP_CAP})`,
         tried:
@@ -1613,15 +1654,19 @@ const agentStarted = ({
                       })
                     : card.tried
             const fixing = kind === 'fix' || kind === 'resent'
+            // A writer answering an open check, or fixing on top of the run
+            // branch, is fixing; its first pass is building.
+            const stage =
+                card.open_check !== null || card.stage === 'fixing'
+                    ? 'fixing'
+                    : 'building'
             if (role === 'test-writer') {
-                // During a ticket review (a retried review fixer) the card
-                // stays in Reviewing at its step.
-                const reviewing = card.stage === 'reviewing'
+                // A retried review fixer stays at its step.
                 return {
                     ...started,
                     tried,
-                    stage: reviewing ? 'reviewing' : 'building',
-                    step: reviewing ? card.step : 0,
+                    stage,
+                    step: card.open_check === 'review' ? card.step : 0,
                     activity: fixing
                         ? `fixing tests (${fix_round}/${LOOP_CAP})`
                         : kind === 'retry'
@@ -1633,8 +1678,7 @@ const agentStarted = ({
                 return {
                     ...started,
                     tried,
-                    stage:
-                        card.stage === 'reviewing' ? 'reviewing' : 'building',
+                    stage,
                     step: 2,
                     activity: fixing
                         ? `fixing (${fix_round}/${LOOP_CAP})`
@@ -1724,9 +1768,12 @@ const agentFinished = ({
                         }),
                     done.tried
                 )
+                // Approved, it joins the run branch next; else a review fix
+                // round follows.
                 return result.verdict === 'approve'
                     ? {
                           ...done,
+                          stage: 'joining',
                           step: ALL_STEPS_DONE,
                           findings,
                           open_check: null,
@@ -1735,6 +1782,7 @@ const agentFinished = ({
                       }
                     : {
                           ...done,
+                          stage: 'fixing',
                           findings,
                           open_check: 'review',
                           tried: ruled,
@@ -1828,9 +1876,9 @@ export const testsSentBackText = ({
 }
 
 /**
- * A ticket sent back onto the run branch builds again: its tests first if
- * test files clashed, else its code; then the checks and a fresh review,
- * whose fix rounds count from zero again.
+ * A ticket sent back onto the run branch is fixed on top of it: its tests
+ * first if test files clashed, else its code; then the checks and a fresh
+ * review, whose fix rounds count from zero again.
  */
 const ticketRebased = ({
     state,
@@ -1844,7 +1892,7 @@ const ticketRebased = ({
         number: record.ticket,
         update: (card) => ({
             ...card,
-            stage: 'building',
+            stage: 'fixing',
             step: record.content.tests.length > 0 ? 0 : 2,
             role: null,
             fix_round: 0,
@@ -2054,11 +2102,18 @@ export const unfinishedBlockers = ({
         return blocker !== undefined && blocker.stage !== 'done'
     })
 
+/** The stages of a ticket the engine is working on. */
+const ACTIVE_STAGES = new Set<TicketStage>([
+    'building',
+    'reviewing',
+    'testing',
+    'fixing',
+    'joining',
+])
+
 const isActive = ({ state }: { state: BoardState }): boolean =>
     state.tickets.some(
-        (ticket) =>
-            ticket.started &&
-            (ticket.stage === 'building' || ticket.stage === 'reviewing')
+        (ticket) => ticket.started && ACTIVE_STAGES.has(ticket.stage)
     ) ||
     state.final_review.state === 'reviewing' ||
     state.final_review.state === 'fixing'

package/board/shared/board-state.ts

@@ -177,10 +177,20 @@ export const RunPhaseSchema = z.enum([
 
 export type RunPhase = z.infer<typeof RunPhaseSchema>
 
+/**
+ * What a ticket is really doing (#549): `building` its first test-writer and
+ * implementer pass, `reviewing` only while a reviewer works, `testing` the red
+ * check or the checks, `fixing` any fix round, `joining` the run branch and
+ * the checks there. Every older stage is still one, so a stored board state
+ * from before still parses.
+ */
 export const TicketStageSchema = z.enum([
     'blocked',
     'building',
     'reviewing',
+    'testing',
+    'fixing',
+    'joining',
     'stuck',
     'done',
     'skipped',

package/engine/agents/role-prompts.ts

@@ -203,8 +203,9 @@ export const CHANGESETS_SECTION = [
 ].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.
+ * The section every reviewer (the ticket-reviewer and each 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',

package/engine/cli/run-modes.ts

@@ -218,8 +218,11 @@ const driveRun = async ({
 }
 
 /** A value of a reloaded config field in a log line; `null` is "none". */
-const fieldValue = (value: string | number | null): string =>
-    value === null ? 'none' : String(value)
+const fieldValue = (value: string | number | string[] | null): string => {
+    if (value === null) return 'none'
+    if (Array.isArray(value)) return `[${value.join(', ')}]`
+    return String(value)
+}
 
 /**
  * The log line for a resume's `config_reloaded` or `config_reload_refused`

package/engine/config/config-reload.ts

@@ -1,3 +1,4 @@
+import isEqual from 'lodash/isEqual'
 import omit from 'lodash/omit'
 import reduce from 'lodash/reduce'
 import { z } from 'zod'
@@ -7,10 +8,10 @@ import type { EngineConfig } from './engine-config'
 /**
  * The config fields a resumed run takes from the repo's
  * `.luca/config.json` again (#516). They say how the engine builds a
- * checkout before its tests, or how long a test may run, not what the
- * tests are, so a run can change them halfway without making its earlier
- * results wrong: a repo that swaps a slow `prepare` for a fast cached one
- * gets it on the next resume.
+ * checkout before its tests, how long a test may run, or which new docs
+ * may be committed, not what the tests are, so a run can change them
+ * halfway without making its earlier results wrong: a repo that swaps a
+ * slow `prepare` for a fast cached one gets it on the next resume.
  *
  * - `prepare`: the command run before each test run in a checkout.
  * - `prepare_timeout_ms`: how long that command may run.
@@ -19,12 +20,16 @@ import type { EngineConfig } from './engine-config'
  *   one counts from the next prepare run.
  * - `test_timeout_ms`: how long each test command may run (#542). Each run
  *   of a test command reads it then, so a new one counts from the next.
+ * - `leftover_allow`: more new markdown the leftover scan lets through
+ *   (#520). Each scan reads it then, so a run stuck on a leftover can be
+ *   unstuck by allowing the file and resuming.
  */
 export const RELOADED_FIELDS = [
     'prepare',
     'prepare_timeout_ms',
     'prepare_concurrency',
     'test_timeout_ms',
+    'leftover_allow',
 ] as const
 
 /**
@@ -61,6 +66,7 @@ export const FROZEN_FIELDS = [
 ] as const
 
 const positiveInt = z.number().int().positive().nullable()
+const patterns = z.array(z.string().min(1)).nullable()
 
 /**
  * One reloaded field that changed: its value in the run before (`from`)
@@ -88,6 +94,11 @@ export const ConfigChangeSchema = z.discriminatedUnion('field', [
         from: positiveInt,
         to: positiveInt,
     }),
+    z.object({
+        field: z.literal('leftover_allow'),
+        from: patterns,
+        to: patterns,
+    }),
 ])
 
 export type ConfigChange = z.infer<typeof ConfigChangeSchema>
@@ -129,8 +140,13 @@ export const configChanges = ({
             from: current.test_timeout_ms ?? null,
             to: next.test_timeout_ms ?? null,
         },
+        {
+            field: 'leftover_allow',
+            from: current.leftover_allow ?? null,
+            to: next.leftover_allow ?? null,
+        },
     ]
-    return all.filter(({ from, to }) => from !== to)
+    return all.filter(({ from, to }) => !isEqual(from, to))
 }
 
 const applyChange = ({
@@ -157,6 +173,10 @@ const applyChange = ({
             return change.to === null
                 ? omit(config, 'test_timeout_ms')
                 : { ...config, test_timeout_ms: change.to }
+        case 'leftover_allow':
+            return change.to === null
+                ? omit(config, 'leftover_allow')
+                : { ...config, leftover_allow: change.to }
     }
 }
 

package/engine/config/engine-config.ts

@@ -92,6 +92,12 @@ export const EngineConfigSchema = z.object({
      * engine's default (`DEFAULT_COMMAND_TIMEOUT_MS`, 5 minutes).
      */
     test_timeout_ms: z.number().int().positive().optional(),
+    /**
+     * Glob patterns for more new markdown the leftover scan lets through,
+     * beyond doc folders, READMEs, and files the repo names (#520), such as
+     * `design/*.md`; left out, none.
+     */
+    leftover_allow: z.array(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/decide-build.ts

@@ -1341,11 +1341,13 @@ const withWriterSection = ({
 }
 
 /**
- * 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).
+ * In a repo with changesets, the writers are told not to write one (#507),
+ * and every reviewer (the ticket-reviewer and each lens) that the engine adds
+ * the run's one at PR time (#507, #545).
  */
 const withChangesetsSections = (step: BuildAction): BuildAction =>
-    step.type === 'launch_lens' && step.lens === 'rules'
+    step.type === 'launch_lens' ||
+    (step.type === 'launch_agent' && step.role === 'ticket-reviewer')
         ? { ...step, prompt: `${step.prompt}\n\n${CHANGESETS_LENS_SECTION}` }
         : withWriterSection({ step, section: CHANGESETS_SECTION })
 

package/engine/core/execute-build.ts

@@ -30,9 +30,10 @@ import { endedText } from '../gates/gate-schemas'
 import {
     importStem,
     isAgentChangeset,
+    leftoverPasses,
+    nameCheckedFiles,
     newCodeFiles,
     scanLeftovers,
-    scratchNamedFiles,
 } from '../gates/leftover-scan'
 import {
     dependenciesChanged,
@@ -462,7 +463,8 @@ 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
+ * file or new markdown (#520) by its basename, as a TOC, `package.json`, a
+ * doc index, 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.
  */
@@ -604,23 +606,26 @@ export const commitIn = async ({
         used_code[path] = await isUsed({ context, cwd, path, added_texts })
     }
     const named: string[] = []
-    for (const path of scratchNamedFiles({ changes })) {
+    for (const path of nameCheckedFiles({ changes })) {
         if (await isNamed({ context, cwd, path, added_texts })) {
             named.push(path)
         }
     }
-    const hits = scanLeftovers({
+    const inputs = {
         changes,
         test_files,
         mention_text,
         used_code,
         named,
-    })
+        leftover_allow: context.config.leftover_allow ?? [],
+    }
+    const hits = scanLeftovers(inputs)
+    const passed = leftoverPasses(inputs)
     context.journal.append({
         kind: 'leftover_scan',
         ticket,
         role: null,
-        content: { stage, hits },
+        content: { stage, hits, ...(passed.length > 0 ? { passed } : {}) },
     })
     if (hits.length > 0) return
     const adopted =

package/engine/core/stuck-text.ts

@@ -41,6 +41,13 @@ const REASON_LINES: Record<StuckReason, string> = {
         'Undoing its join would have rewound the run branch over other work, so the run branch was left alone.',
 }
 
+/**
+ * How to keep a flagged doc the repo wants, for a `leftovers_found` stuck
+ * (#520); `retry` is the reply that retries it.
+ */
+const leftoverAllowHint = ({ retry }: { retry: string }): string =>
+    `If one is a doc the repo wants, add a pattern for it to \`leftover_allow\` in the repo's \`.luca/config.json\` instead, resume the run (only a resume reads the config again, a plain \`retry\` doesn't), then reply ${retry}.`
+
 /** What the user could do, per reason; `n` is the ticket. */
 const suggestion = ({
     reason,
@@ -58,7 +65,7 @@ const suggestion = ({
         case 'nothing_new_to_test':
             return `A ticket that changes no behavior is a refactor ticket: add the \`${REFACTOR_LABEL}\` label, then reply ${retry}. It is built again as a refactor, with no new tests.`
         case 'leftovers_found':
-            return `Delete those files in the worktree (or move them out of it), then reply ${retry}.`
+            return `Delete those files in the worktree (or move them out of it), then reply ${retry}. ${leftoverAllowHint({ retry })}`
         case 'gates_failed':
             return `Fix the failing check in the worktree, or make the ticket clearer, then reply ${retry}.`
         case 'bad_test':
@@ -198,7 +205,7 @@ const finalSuggestion = ({ reason }: { reason: StuckReason }): string => {
         case 'changes_requested':
             return "Fix the open findings in the run branch's worktree, then reply `retry`; or reply `ship` if they can wait for review in the PR."
         case 'leftovers_found':
-            return "Delete those files in the run branch's worktree, then reply `retry`."
+            return `Delete those files in the run branch's worktree, then reply \`retry\`. ${leftoverAllowHint({ retry: '`retry`' })}`
         default:
             return "Read the last error, fix what trips it in the run branch's worktree, then reply `retry`; or reply `ship` to open the PR anyway."
     }

package/engine/gates/gate-schemas.ts

@@ -82,3 +82,32 @@ export const LeftoverHitSchema = z.object({
 })
 
 export type LeftoverHit = z.infer<typeof LeftoverHitSchema>
+
+/**
+ * Why the leftover scan let a new markdown file through (#520): it sits in a
+ * doc place (a `docs` or `adr` folder, or a `README.md`), a tracked or newly
+ * added non-test file names it, or a `leftover_allow` pattern matches it.
+ */
+export const LeftoverPassReasonSchema = z.enum([
+    'doc_place',
+    'named_by_repo',
+    'config_pattern',
+])
+
+export type LeftoverPassReason = z.infer<typeof LeftoverPassReasonSchema>
+
+/**
+ * A new markdown file the leftover scan let through, and why, as the journal
+ * keeps it. The reason is a string there, so a later reason still reads.
+ */
+export const LeftoverPassSchema = z.object({
+    path: z.string(),
+    reason: z.string(),
+})
+
+/** A new markdown file the leftover scan let through, as the scan returns it. */
+export const LeftoverPassResultSchema = LeftoverPassSchema.extend({
+    reason: LeftoverPassReasonSchema,
+})
+
+export type LeftoverPass = z.infer<typeof LeftoverPassResultSchema>