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

package/engine/core/final-failure-cap.ts

@@ -0,0 +1,38 @@
+/**
+ * The cap on a final review role's failed tries (`failureCap`): the stuck step
+ * once a failed turn used up the role's tries, or its engine failures in a row.
+ */
+import { stuck, type FinalReviewAction } from './final-review-action'
+import { MAX_ENGINE_FAILURES, MAX_FIX_ROUNDS } from './loop-caps'
+
+import type { FinalReviewState, ReplayedAgentFailure } from '../journal/replay'
+
+/**
+ * The stuck step when a failed turn used up its role's tries (or engine
+ * failures in a row), else `null`: the role gets another go.
+ */
+export const failureCap = ({
+    review,
+    failed,
+}: {
+    review: FinalReviewState
+    failed: ReplayedAgentFailure
+}): FinalReviewAction | null => {
+    const { role, error, failure } = failed
+    if (failure === 'engine') {
+        const count = review.engine_failures[role] ?? 0
+        return count >= MAX_ENGINE_FAILURES
+            ? stuck({
+                  reason: 'agent_failed',
+                  detail: `The engine failed to run the ${role} ${count} times in a row: ${error}`,
+              })
+            : null
+    }
+    const tries = review.failed_tries[role] ?? 0
+    return tries >= MAX_FIX_ROUNDS
+        ? stuck({
+              reason: 'agent_failed',
+              detail: `The ${role} failed ${tries} tries in the final review; the last one: ${error}`,
+          })
+        : null
+}

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

@@ -0,0 +1,125 @@
+/**
+ * The final review's decision step, as types: its actions
+ * (`FinalReviewAction`, `isFinalReviewAction`), where it stands
+ * (`FinalReviewDecision`), what it reads (`DecideArgs`), and the stuck step
+ * (`stuck`).
+ */
+import type { FinalFixerRole } from './final-review-text'
+
+import type { PromptRunNote } from '../agents/role-prompts'
+import type { LensName, LensRole } from '../agents/role-results'
+import type { StuckReason } from '../journal/journal-record'
+import type {
+    FinalReviewState,
+    ReplayedGates,
+    ReplayedSnapshot,
+    ReplayedWorktree,
+} from '../journal/replay'
+import type { CrashCounts } from '../journal/step-records'
+
+/** The final review's steps, once every ticket pushed and before the PR. */
+export type FinalReviewAction =
+    /**
+     * Start a final review round: read the run branch's HEAD, the files
+     * since `from_sha`, and the config's rule files, then journal
+     * `final_review_started`. `fresh`: the fresh pass (#548).
+     */
+    | {
+          type: 'start_final_review'
+          round: number
+          from_sha: string
+          lenses: LensName[]
+          fresh?: boolean
+      }
+    /** Start a fresh, read-only lens reviewer on the run branch. */
+    | { type: 'launch_lens'; lens: LensName; role: LensRole; prompt: string }
+    /** Run the config's slow tests on the run branch (#563), once round 1's lenses are in. */
+    | { type: 'run_final_slow_tests' }
+    /** Every lens due this round approved. */
+    | { type: 'pass_final_review' }
+    /** A fix round on the lenses' findings starts. */
+    | { type: 'start_final_fix'; round: number }
+    /** Start a fresh fixer on the run branch's worktree. */
+    | {
+          type: 'launch_final_fixer'
+          role: FinalFixerRole
+          prompt: string
+          may_edit_tests: boolean
+      }
+    /** Send a follow-up to a fixer's open session (failed gates, a failed try). */
+    | {
+          type: 'follow_up_final_fixer'
+          role: FinalFixerRole
+          session_id: string
+          message: string
+      }
+    /** Run the engine config's gates on the run branch's worktree. */
+    | { type: 'run_final_gates' }
+    /** Scan for leftovers, then commit the fixes on the run branch. */
+    | { type: 'commit_final_fix'; round: number; message: string }
+    /** Push the run branch with the fixes to `origin`. */
+    | { type: 'push_final_fixes'; branch: string }
+    /** The engine can't safely pick the final review's next step by itself. */
+    | { type: 'mark_final_review_stuck'; reason: StuckReason; detail: string }
+
+const FINAL_REVIEW_ACTION_TYPES: ReadonlySet<string> = new Set<
+    FinalReviewAction['type']
+>([
+    'start_final_review',
+    'launch_lens',
+    'run_final_slow_tests',
+    'pass_final_review',
+    'start_final_fix',
+    'launch_final_fixer',
+    'follow_up_final_fixer',
+    'run_final_gates',
+    'commit_final_fix',
+    'push_final_fixes',
+    'mark_final_review_stuck',
+])
+
+/**
+ * Whether an action is one of the final review's.
+ *
+ * @example
+ * isFinalReviewAction({ type: 'run_final_gates' }) // true
+ */
+export const isFinalReviewAction = <Action extends { type: string }>(
+    action: Action
+): action is Extract<Action, FinalReviewAction> =>
+    FINAL_REVIEW_ACTION_TYPES.has(action.type)
+
+/**
+ * Where the final review stands for the build half of the decision step:
+ * still working (these actions can run now), passed or shipped (open the
+ * PR), or stuck (end the run until a reply).
+ */
+export type FinalReviewDecision =
+    | { status: 'working'; actions: FinalReviewAction[] }
+    | { status: 'passed' }
+    | { status: 'shipped' }
+    | { status: 'stuck'; reason: StuckReason; detail: string }
+
+/** What the final review's decision step reads from the run. */
+export type DecideArgs = {
+    review: FinalReviewState
+    /** Crashes in a row per scheduler key; the final review's are its own. */
+    crashes: CrashCounts
+    snapshot: ReplayedSnapshot
+    run_branch: ReplayedWorktree
+    /** The latest gates on the run branch. */
+    run_branch_gates: ReplayedGates | null
+    /** The run notes a fresh agent gets (`newestRunNotes`). */
+    run_notes: PromptRunNote[]
+    /** The config's test setup files; none if left out. */
+    setup_files?: string[]
+}
+
+/** The step that marks the final review stuck, with its reason. */
+export const stuck = ({
+    reason,
+    detail,
+}: {
+    reason: StuckReason
+    detail: string
+}): FinalReviewAction => ({ type: 'mark_final_review_stuck', reason, detail })

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

@@ -5,6 +5,7 @@ import {
     findingList,
     FIX_RULES,
     gateResults,
+    handoffSection,
     responseText,
     RULING_RULES,
 } from './review-text'
@@ -15,13 +16,14 @@ import {
     type PromptRunNote,
 } from '../agents/role-prompts'
 import { lensRole, type Finding, type LensName } from '../agents/role-results'
-import type {
-    FinalFinding,
-    FinalReviewFix,
-    FinalReviewState,
-    ReplayedGates,
-    ReplayedSnapshot,
-    RuleFile,
+import {
+    handoffRole,
+    type FinalFinding,
+    type FinalReviewFix,
+    type FinalReviewState,
+    type ReplayedGates,
+    type ReplayedSnapshot,
+    type RuleFile,
 } from '../journal/replay'
 
 /**
@@ -191,7 +193,8 @@ const findingsSection = ({
 /**
  * The prompt a fresh final review fixer starts with: its task, the spec,
  * every ticket, and its findings (the test findings for the test-writer,
- * the code findings for the implementer). An implementer launched only to
+ * the code findings for the implementer, or the findings the other fixer
+ * answered `other_role`, #616). An implementer launched only to
  * fix failed gates (the round had only test findings) gets the gates'
  * output instead. The engine journals it word for word.
  *
@@ -224,7 +227,13 @@ export const finalFixerPrompt = ({
                   "You are fixing the final review's findings on the whole run branch. The test fixes are in the worktree, uncommitted. The gates failed. Fix the code so every gate passes, then answer.",
                   failedChecks({ gates }),
               ].join('\n\n')
-            : findingsSection({ fix, kind })
+            : handoffRole({ fix }) === role
+              ? handoffSection({
+                    fix,
+                    role,
+                    heading: `Final review fix round ${fix.round}`,
+                })
+              : findingsSection({ fix, kind })
     return [
         `# Your role: ${role}`,
         FIXER_TASKS[role],
@@ -248,31 +257,68 @@ export const openFinalFindingsText = ({
     findings: FinalFinding[]
 }): string => findingList(findings)
 
+/** Each open finding as a PR line, with its lens, severity, and file. */
+const openFindingLines = ({
+    findings,
+}: {
+    findings: FinalFinding[]
+}): string[] =>
+    findings.map(
+        ({ lens, severity, file, id, title }) =>
+            `- ${lens} lens, ${SEVERITY_TEXT[severity]}${file === null ? '' : ` (${file})`}: ${id} ${title}`
+    )
+
+/**
+ * The "Open findings" section a PR starts with when the fresh pass's
+ * re-check (#548) still holds findings open: the final review passed
+ * without them, so the owner reviews them.
+ *
+ * @example
+ * freshFindingsSection({ findings })
+ * // '## Open findings\n\n...\n\n- security lens, blocker (src/sum.ts): security-S2 Sum overflows silently'
+ */
+export const freshFindingsSection = ({
+    findings,
+}: {
+    findings: FinalFinding[]
+}): string =>
+    [
+        '## Open findings',
+        "After the final review's last fix round, every lens read the whole branch once more. Its findings got one fix round, and the lenses still hold these open, so this PR opened with them for you to review:",
+        openFindingLines({ findings }).join('\n'),
+    ].join('\n\n')
+
 /**
  * The "Open findings" section a shipped final review's PR starts with: why
- * it was stuck, and each finding still open with its lens, severity, and
- * file.
+ * it was stuck, each finding still open with its lens, severity, and file,
+ * and the files of the edits left uncommitted at ship time (#509), which
+ * went in their own commit without a review.
  *
  * @example
- * shippedFindingsSection({ findings, stuck })
+ * shippedFindingsSection({ findings, stuck, edits: null })
  * // '## Open findings\n\n...\n\n- security lens, should-fix (src/sum.ts): security-S1 Sum trusts its input'
  */
 export const shippedFindingsSection = ({
     findings,
     stuck,
+    edits,
 }: {
     findings: FinalFinding[]
     stuck: { reason: string; detail: string }
+    /** The commit of the edits left uncommitted at ship time, if any. */
+    edits: { message: string; files: string[] } | null
 }): string => {
-    const lines = findings.map(
-        ({ lens, severity, file, id, title }) =>
-            `- ${lens} lens, ${SEVERITY_TEXT[severity]}${file === null ? '' : ` (${file})`}: ${id} ${title}`
-    )
+    const lines = openFindingLines({ findings })
     return [
         '## Open findings',
         `The final review got stuck (\`${stuck.reason}\`) and you replied \`ship\`, so this PR opened with the final review unfinished.`,
         lines.length === 0
             ? `No lens finding was open. Why it was stuck:\n\n${stuck.detail}`
             : `These findings are still open:\n\n${lines.join('\n')}`,
-    ].join('\n\n')
+        edits === null || edits.files.length === 0
+            ? ''
+            : `Uncommitted fixer edits, not reviewed: these files were changed in the run branch's worktree when you replied \`ship\`, so they went in their own commit, "${edits.message}":\n\n${edits.files.map((file) => `- ${file}`).join('\n')}`,
+    ]
+        .filter((part) => part !== '')
+        .join('\n\n')
 }

package/engine/core/final-stuck-text.ts

@@ -0,0 +1,86 @@
+/**
+ * The comment on the spec issue when the final review is stuck.
+ */
+import compact from 'lodash/compact'
+
+import { fenced, plural } from './stuck-format'
+import { leftoverAllowHint, reasonLine } from './ticket-stuck-text'
+
+import type { StuckReason } from '../journal/journal-record'
+import type { FinalReviewState, ReplayedWorktree } from '../journal/replay'
+
+/** Why the final review is stuck, in one line, where it differs from a ticket. */
+const FINAL_REASON_LINES: Partial<Record<StuckReason, string>> = {
+    changes_requested: 'The final review still asks for changes.',
+    gates_failed: "The checks still fail after the final review's fixes.",
+    bad_test:
+        "While fixing the final review's findings, the implementer sent a test back as bad.",
+    agent_failed: 'A final review agent failed on every try it had.',
+    crashed:
+        'The engine crashed in the same final review step, again and again.',
+    environment_failed:
+        "A fixer says the final checks' failure is not the branch's fault, but the rerun failed the same way, or its reruns ran out.",
+}
+
+/** What the owner could do about the stuck final review, per reason. */
+const finalSuggestion = ({ reason }: { reason: StuckReason }): string => {
+    switch (reason) {
+        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\`. ${leftoverAllowHint({ retry: '`retry`' })}`
+        case 'setup_change_needed':
+            return "Make that change yourself in the run branch's worktree, then reply `retry`; or reply `ship` to open the PR anyway."
+        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."
+    }
+}
+
+/**
+ * The comment on the spec issue when the final review is stuck: why (one
+ * line), what was tried, the last error, a suggestion, and the replies:
+ * `retry`, `stop`, and `ship` (never `skip`).
+ *
+ * @example
+ * finalStuckComment({ review, run_branch })
+ * // '**The final review is stuck**\n\nWhy: The final review still asks for changes. ...'
+ */
+export const finalStuckComment = ({
+    review,
+    run_branch,
+}: {
+    review: FinalReviewState
+    run_branch: ReplayedWorktree
+}): string => {
+    const stuck = review.stuck ?? { reason: 'agent_failed', detail: '' }
+    const tries = Object.entries(review.failed_tries).flatMap(
+        ([role, count]) =>
+            count === undefined || count === 0
+                ? []
+                : [`${plural(count, 'failed try')} by the ${role}`]
+    )
+    const tried = compact([
+        review.round > 1 && plural(review.round - 1, 'fix round'),
+        review.gate_fix_rounds > 0 &&
+            `${plural(review.gate_fix_rounds, 'fix round')} on the checks`,
+        ...tries,
+    ])
+    return [
+        '**The final review is stuck**',
+        [
+            `Why: ${FINAL_REASON_LINES[stuck.reason] ?? reasonLine({ reason: stuck.reason })}`,
+            `Tried: ${tried.length === 0 ? 'Nothing more: another try would fail the same way.' : `${tried.join(', ')}.`}`,
+            `Suggestion: ${finalSuggestion({ reason: stuck.reason })}`,
+            `Run branch worktree: \`${run_branch.path}\` (a \`retry\` keeps your edits there)`,
+        ].join('\n'),
+        `Last error:\n\n${fenced(stuck.detail)}`,
+        [
+            'Reply with one word on this issue:',
+            '- `retry`: fix the open findings again with fresh agents and fresh counts, keeping your edits.',
+            '- `ship`: open the PR anyway, with the open findings listed at the top.',
+            '- `stop`: end the run without a PR. The branch is kept.',
+            '',
+            'Only the spec owner counts.',
+        ].join('\n'),
+    ].join('\n\n')
+}

package/engine/core/fix-loop-text.ts

@@ -1,4 +1,5 @@
 import { rejoinOpening, type RejoinContext } from '../agents/role-prompts'
+import type { BadTest } from '../agents/role-results'
 import type { AgentFailure } from '../journal/journal-record'
 import type { ReplayedGates, ReplayedRedCheck } from '../journal/replay'
 import { clipOutput } from '../shell/run-command'
@@ -49,13 +50,35 @@ const FAILED_TRY_OPENINGS: Record<Exclude<AgentFailure, 'engine'>, string> = {
     agent: 'Your last turn failed before it gave a result.',
     result: "Your last turn ended without a result that fits your role's schema.",
     guard: 'Your last turn changed things your role may not change.',
+    evidence:
+        'The engine checked the evidence in your "already_done" answer, and some of it did not check out.',
+    chore: 'The engine could not do every chore your last result asked for ("file_modes", "run_generators").',
+}
+
+const FIX_CHORES =
+    'Your work is still in the worktree, with every chore the engine could do. Fix what the error names (ask only for paths your role may write and generators the repo names, and fix what made a generator fail), then answer with your full result.'
+
+const TRY_AGAIN =
+    "The engine undid every change your role may not make; the rest of your work is still in the worktree. Try again, keeping to your role's rules, then answer with your full result."
+
+const CHECK_EVIDENCE_AGAIN =
+    'If you named the wrong commits or tests, answer "already_done" again with the right ones: commits on the base branch, and tests that exist and pass there. ' +
+    'If the work is not all on the base branch, or a criterion has no passing test there, write the tests and answer "tests_written" instead.'
+
+/** What to do next, for a failure whose closing isn't `TRY_AGAIN`. */
+const FAILED_TRY_CLOSINGS: Partial<Record<AgentFailure, string>> = {
+    evidence: CHECK_EVIDENCE_AGAIN,
+    chore: FIX_CHORES,
 }
 
 /**
  * The follow-up an agent gets after a failed try (its turn failed, gave no
  * usable result, or broke its role's rules): what failed, the error, that
  * the engine undid every change the role may not make, and to try again.
- * The engine journals it word for word.
+ * A test-writer whose `already_done` evidence did not check out (#495)
+ * hears what did not, and to fix its answer or write the tests instead.
+ * A writer whose chores the engine could not do (#618) hears to fix what
+ * the error names. The engine journals it word for word.
  *
  * @example
  * const message = failedTryMessage({ failure: 'guard', error: '- wrote src/sum.ts, which a test-writer may not write' })
@@ -70,7 +93,7 @@ export const failedTryMessage = ({
     [
         FAILED_TRY_OPENINGS[failure],
         `## Error\n\n${clipOutput({ text: error })}`,
-        "The engine undid every change your role may not make; the rest of your work is still in the worktree. Try again, keeping to your role's rules, then answer with your full result.",
+        FAILED_TRY_CLOSINGS[failure] ?? TRY_AGAIN,
     ].join('\n\n')
 
 /**
@@ -94,6 +117,30 @@ export const clashFixMessage = ({
             'Never edit a test file. Make every gate pass, then answer again.',
     ].join('\n\n')
 
+/**
+ * What the implementer is told once the test-writer updated the tests it
+ * sent back after a rebase (#489): which test, the test-writer's summary,
+ * and to finish the ticket on top of the run branch. A follow-up's message,
+ * or a fresh implementer's prompt section. The engine journals it word for
+ * word.
+ *
+ * @example
+ * const message = testsUpdatedMessage({ bad_test, summary: 'Expect the hint line.' })
+ */
+export const testsUpdatedMessage = ({
+    bad_test,
+    summary,
+}: {
+    bad_test: BadTest
+    summary: string
+}): string =>
+    [
+        '## The test-writer updated the tests',
+        `You sent back ${[bad_test.file, bad_test.name].filter(Boolean).join(' > ') || 'a test'} as a bad test. The test-writer updated this ticket's tests to fit the run branch${summary.trim() === '' ? '.' : `: ${summary.trim()}`}`,
+        'Finish the ticket on top of the run branch: resolve any conflict markers left, keep what the run branch has and what this ticket adds, and make every gate pass. ' +
+            'Never edit a test file. If a test is still wrong, answer "bad_test" with your reason.',
+    ].join('\n\n')
+
 /**
  * The section a fresh agent gets when a crash cut off an earlier agent's
  * turn at its step: it starts fresh, and the worktree may hold that turn's

package/engine/core/left-out.ts

@@ -0,0 +1,120 @@
+import type { LeftOutTicket } from '../intake/intake-schemas'
+import { HUMAN_LABEL } from '../tracker/tracker'
+
+/**
+ * Words for the tickets intake left out for a person (#499): a ticket with
+ * `ready-for-human`, or one that waits on such a ticket. The PR, the run's
+ * end, and the board all say it the same way.
+ */
+
+/** Issue numbers as `#12`, `#12 and #13`, or `#12, #13 and #14`. */
+const numbersText = ({ numbers }: { numbers: number[] }): string => {
+    const refs = numbers.map((number) => `#${number}`)
+    const last = refs.at(-1) ?? ''
+    return refs.length <= 1
+        ? last
+        : `${refs.slice(0, -1).join(', ')} and ${last}`
+}
+
+/**
+ * Why a left-out ticket isn't in the run, in words.
+ *
+ * @example
+ * leftOutWhy({ ticket: { reason: 'for_a_person', ... } }) // 'for a person'
+ * leftOutWhy({ ticket: { reason: 'waits_on_person', waits_on: [12], through: [13], ... } })
+ * // 'waits on #12, which is for a person (through #13)'
+ */
+export const leftOutWhy = ({ ticket }: { ticket: LeftOutTicket }): string => {
+    if (ticket.reason === 'for_a_person') return 'for a person'
+    const which =
+        ticket.waits_on.length === 1
+            ? 'which is for a person'
+            : 'which are for a person'
+    const through =
+        ticket.through.length === 0
+            ? ''
+            : ` (through ${numbersText({ numbers: ticket.through })})`
+    return `waits on ${numbersText({ numbers: ticket.waits_on })}, ${which}${through}`
+}
+
+/**
+ * The PR's sections for the tickets left out for a person: "For a person"
+ * (the `ready-for-human` tickets) and "Waiting on a person" (the tickets
+ * blocked by them). Empty when none was left out.
+ *
+ * @example
+ * leftOutSections({ left_out })
+ * // ['## For a person\n\n...\n\n- #12 Make the store page', '## Waiting on a person\n\n...']
+ */
+export const leftOutSections = ({
+    left_out,
+}: {
+    left_out: LeftOutTicket[]
+}): string[] => {
+    const people = left_out.filter(({ reason }) => reason === 'for_a_person')
+    const waiting = left_out.filter(
+        ({ reason }) => reason === 'waits_on_person'
+    )
+    return [
+        people.length === 0
+            ? ''
+            : `## For a person\n\nTickets labeled \`${HUMAN_LABEL}\`. An agent doesn't build them, so this PR doesn't close them.\n\n` +
+              people
+                  .map(({ number, title }) => `- #${number} ${title}`)
+                  .join('\n'),
+        waiting.length === 0
+            ? ''
+            : "## Waiting on a person\n\nTickets that can't be built until a person's ticket is done. A later run builds them.\n\n" +
+              waiting
+                  .map(
+                      (ticket) =>
+                          `- #${ticket.number} ${ticket.title}: ${leftOutWhy({ ticket })}`
+                  )
+                  .join('\n'),
+    ].filter((section) => section !== '')
+}
+
+/**
+ * Why a run ended with nothing to do, in one line: every ticket closed,
+ * the work already done (#484), or the rest left for a person (#499).
+ *
+ * @example
+ * nothingToDoText({ content: { closed_tickets: [11], already_done: [], left_out: [] } })
+ * // 'Nothing to do: every ticket of the spec is closed.'
+ */
+export const nothingToDoText = ({
+    content,
+}: {
+    content: {
+        closed_tickets: number[]
+        already_done: number[]
+        left_out: LeftOutTicket[]
+    }
+}): string => {
+    const numbersOf = (reason: LeftOutTicket['reason']) =>
+        content.left_out
+            .filter((ticket) => ticket.reason === reason)
+            .map(({ number }) => number)
+    const people = numbersOf('for_a_person')
+    const waiting = numbersOf('waits_on_person')
+    const parts = [
+        content.already_done.length === 0
+            ? ''
+            : `the work of ${content.already_done.map((number) => `#${number}`).join(', ')} was already on the base branch`,
+        people.length === 0
+            ? ''
+            : `${numbersText({ numbers: people })} ${people.length === 1 ? 'is' : 'are'} for a person`,
+        waiting.length === 0
+            ? ''
+            : `${numbersText({ numbers: waiting })} ${waiting.length === 1 ? 'waits' : 'wait'} on a ticket for a person`,
+    ].filter((part) => part !== '')
+    if (parts.length === 0) {
+        return 'Nothing to do: every ticket of the spec is closed.'
+    }
+    const last = parts.at(-1) ?? ''
+    const text =
+        parts.length === 1
+            ? last
+            : `${parts.slice(0, -1).join(', ')}, and ${last}`
+    return `Nothing to do: ${text}.`
+}