@alecsibilia/luca 14.0.0-alpha.34 → 14.0.0-alpha.36

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.36
+
+No changes in this release.
+
+## 14.0.0-alpha.35
+
+No changes in this release.
+
 ## 14.0.0-alpha.34
 
 No changes in this release.

package/README.md

@@ -42,6 +42,10 @@ If a ticket gets stuck, Luca comments on the spec and waits for your one-word re
 
 After a run, type `/luca-retro` the same way to look back on it: it reads the run's journal, ranks what went wrong, and suggests a check, a rule, or a deletion for each, not a code change. It opens an issue for each one you pick, once you say yes.
 
+To get any pull request ready for review, in any repo, type `/luca-pr-prep [PR number or URL]`: it writes the PR's story, a guide that walks a reviewer through the change in call order, with the why, the proof, and the blast radius of each changed region. In your own repos it posts the story on the PR and adds the `review-ready` label; in anyone else's it saves the story on your computer and posts nothing.
+
+Once a PR has been reviewed, type `/luca-pr-address [PR number or URL]`: it reads every review comment and check alert, fixes what was asked or asks you a question, replies on each thread, runs the repo's checks, pushes, and brings the story up to date. It never declines one of your own comments, and it never merges.
+
 ## Commands
 
 | Command | What it does |
@@ -92,7 +96,7 @@ This is the one package that goes to npm. It's TypeScript source with no build a
 | ------ | ---------- |
 | `engine/` | The engine's source, from [`packages/engine/src`](../engine/src). Both bins point into it. |
 | `board/` | The board plugin's folder, from [`packages/board`](../board): `paseo-plugin.json`, its entry points, its client, server, and shared code, and its own `package.json`, so Paseo can install it as a folder source. |
-| `skills/` | Luca's own Claude Code skills, `luca-unstick`, `luca-retro` and `luca-spec-check`, from [`packages/engine/skills`](../engine/skills). `luca init` and `luca upgrade` copy every folder in it with a `SKILL.md` to `~/.claude/skills`. |
+| `skills/` | Luca's own Claude Code skills, such as `luca-unstick`, `luca-retro`, `luca-spec-check`, `luca-pr-prep` and `luca-pr-address`, from [`packages/engine/skills`](../engine/skills). `luca init` and `luca upgrade` copy every folder in it with a `SKILL.md` to `~/.claude/skills`. |
 | `LICENSE` | The repo's license. |
 
 Test files and test helpers stay out. The engine and the board stay private workspace packages, and this package lists every package they import at runtime as its own dependency.

package/board/package.json

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

package/board/server/describe-record.ts

@@ -26,6 +26,7 @@ import {
     runReasonText,
     roleWords,
     shortSha,
+    STORY_WRITER,
     testsSentBackText,
 } from './reduce-board'
 
@@ -149,6 +150,13 @@ export const describeRecord = ({
                     tone: 'info',
                 })
             }
+            // The story-writer (#743) is no final review agent.
+            if (record.content.role === STORY_WRITER) {
+                return event({
+                    text: "The story-writer writes the pull request's review story.",
+                    tone: 'info',
+                })
+            }
             return record.ticket === null
                 ? finalStartedText({ record })
                 : startedText({ before, after, record })
@@ -156,6 +164,12 @@ export const describeRecord = ({
             if (record.content.role === LEARNER) {
                 return learnerFinishedText({ record })
             }
+            if (record.content.role === STORY_WRITER) {
+                return event({
+                    text: 'The story-writer answered; the engine checks and saves its story.',
+                    tone: 'info',
+                })
+            }
             return record.ticket === null
                 ? finalFinishedText({ record })
                 : finishedText({ before, record })
@@ -164,9 +178,11 @@ export const describeRecord = ({
             const who =
                 role === LEARNER
                     ? 'The learner'
-                    : record.ticket === null
-                      ? `Final review: the ${roleWords({ role })}`
-                      : `${at}the ${role}`
+                    : role === STORY_WRITER
+                      ? 'The story-writer'
+                      : record.ticket === null
+                        ? `Final review: the ${roleWords({ role })}`
+                        : `${at}the ${role}`
             return event({
                 text: `${who} ${failureText({ failure })}: ${error.split('\n')[0] ?? ''}`,
                 tone: failure === 'engine' ? 'warning' : 'danger',

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

package/board/server/reduce-board-agents.ts

@@ -1,12 +1,14 @@
 /**
  * An agent's turn on a ticket or the final review: its start, how it
- * finished, and how it failed.
+ * finished, and how it failed. The learner's and the story-writer's turns
+ * are neither.
  */
 import type { BoardRecord } from './board-vocabulary'
 import { agentStarted } from './reduce-board-agent-start'
 import { countFindings, failureText, roleWords } from './reduce-board-text'
 import {
     LEARNER,
+    STORY_WRITER,
     finalTried,
     updateTicket,
     withLearner,
@@ -118,6 +120,9 @@ export const applyAgentKind = ({
     record: AgentRecord
 }): BoardState => {
     const { ticket } = record
+    // The story-writer (#743) has no ticket and is no final review agent;
+    // the board doesn't show the PR's story, so its turns change nothing.
+    if (record.content.role === STORY_WRITER) return state
     switch (record.kind) {
         case 'agent_started':
             // The learner (#370) has no ticket and is no final review agent.

package/board/server/reduce-board-update.ts

@@ -21,6 +21,12 @@ export const DETAIL_MAX = 2000
 /** The learner's role (#370): its records have no ticket. */
 export const LEARNER = 'learner'
 
+/**
+ * The story-writer's role (#743): it writes the opened PR's story. Its
+ * records have no ticket, and are never the final review's.
+ */
+export const STORY_WRITER = 'story-writer'
+
 export const withLearner = ({
     state,
     learner,

package/board/server/reduce-board.ts

@@ -71,7 +71,7 @@ export {
     shortSha,
     testsSentBackText,
 } from './reduce-board-text'
-export { LEARNER } from './reduce-board-update'
+export { LEARNER, STORY_WRITER } from './reduce-board-update'
 
 /** Record kinds that don't mean the engine moved on after a stop. */
 const QUIET_KINDS = new Set([

package/engine/agents/claude-options.ts

@@ -12,6 +12,7 @@ import {
     IntegrationLensResultSchema,
     LearnerResultSchema,
     LensReviewResultSchema,
+    StoryWriterResultSchema,
     TestWriterResultSchema,
     TicketReviewResultSchema,
     type AgentRole,
@@ -133,6 +134,7 @@ const RESULT_SCHEMAS: Record<AgentRole, z.ZodType> = {
     'integration-lens': IntegrationLensResultSchema,
     'rules-lens': LensReviewResultSchema,
     learner: LearnerResultSchema,
+    'story-writer': StoryWriterResultSchema,
 }
 
 /** A role's result schema as JSON Schema, for the SDK's structured output. */

package/engine/agents/role-effort.ts

@@ -30,6 +30,8 @@ export const ROLE_EFFORT: Record<AgentRole, EffortLevel> = {
     'security-lens': REVIEW_EFFORT,
     'integration-lens': REVIEW_EFFORT,
     'rules-lens': REVIEW_EFFORT,
+    // No config key (#743): it always runs at high.
+    'story-writer': 'high',
 }
 
 /**

package/engine/agents/role-instructions.ts

@@ -13,6 +13,11 @@ import {
 import { LEARNER, LEARNER_RULES } from './learner-instructions'
 import { LENS, REVIEWER } from './reviewer-instructions'
 import { lensOf, type AgentRole } from './role-results'
+import {
+    STORY_WRITER,
+    STORY_WRITER_RULES,
+    storyFormat,
+} from './story-writer-instructions'
 import { IMPLEMENTER, TEST_WRITER } from './writer-instructions'
 
 import type { EngineConfig } from '../config/engine-config'
@@ -27,8 +32,8 @@ import { canMessage } from '../messages/agent-messages'
  * and implementers with messaging are told how agent messages work;
  * reviewers aren't. Each final review lens gets its own focus; the
  * integration lens also gives the PR's Summary picture and Merge Danger
- * (#513). The learner (#370) gets its own task and rules: no shell,
- * nothing written. Every role is told about its read-only helpers (#627),
+ * (#513). The learner (#370) and the story-writer (#743) get their own
+ * task and rules: no shell, nothing written. Every role is told about its read-only helpers (#627),
  * and what its sandbox blocks (#540). The writers, as final review fixers
  * too, are told where the repo's rule files are (#646).
  *
@@ -53,6 +58,16 @@ export const roleInstructions = ({
     // The learner has no shell and no agent messages, and its rules differ.
     if (role === 'learner')
         return [LEARNER, HELPERS, SANDBOX, LEARNER_RULES].join('\n\n')
+    // The story-writer (#743) has no shell either, carries the skill's
+    // field guide word for word, and has rules of its own.
+    if (role === 'story-writer')
+        return [
+            STORY_WRITER,
+            storyFormat().trim(),
+            HELPERS,
+            SANDBOX,
+            STORY_WRITER_RULES,
+        ].join('\n\n')
     const lens = lensOf({ role })
     const task =
         lens !== null

package/engine/agents/role-prompts.ts

@@ -75,6 +75,8 @@ const ROLE_TASKS: Record<AgentRole, string> = {
     learner:
         "Read this run's journal digest below and propose only durable lessons that will help future runs. " +
         "Pick each one's type, and list the ids of the shown memories that actually helped. Write nothing.",
+    'story-writer':
+        "Write the review story of this run's pull request: its summary, its map, and its walk, from the code at its head. Write nothing.",
 }
 
 /**

package/engine/agents/role-results.ts

@@ -30,9 +30,9 @@ export type LensRole = (typeof LENS_ROLES)[number]
 
 /**
  * The roles an agent can play: the ticket roles while a ticket is built, one
- * reviewer role per lens in the final review, and the learner at the end of
- * a run (#370). The final review's fixers are the test-writer and the
- * implementer.
+ * reviewer role per lens in the final review, the learner at the end of
+ * a run (#370), and the story-writer once the run's PR is open (#743). The
+ * final review's fixers are the test-writer and the implementer.
  */
 export const AgentRoleSchema = z.enum([
     'test-writer',
@@ -40,6 +40,7 @@ export const AgentRoleSchema = z.enum([
     'ticket-reviewer',
     ...LENS_ROLES,
     'learner',
+    'story-writer',
 ])
 
 export type AgentRole = z.infer<typeof AgentRoleSchema>
@@ -370,6 +371,20 @@ export const LearnerResultSchema = z.object({
 
 export type LearnerResult = z.infer<typeof LearnerResultSchema>
 
+/**
+ * The story-writer's result (#743): the parts of a PR's story only a reader
+ * of the code writes. Loose on purpose, so a wrong field inside is named by
+ * the story schema's own reader (`readStory`), not lost in a failed turn.
+ * Any other top-level key is dropped.
+ */
+export const StoryWriterResultSchema = z.object({
+    summary: z.record(z.string(), z.unknown()),
+    map: z.record(z.string(), z.unknown()),
+    stops: z.array(z.unknown()),
+})
+
+export type StoryWriterResult = z.infer<typeof StoryWriterResultSchema>
+
 const lensResult = <Role extends LensRole>(role: Role) =>
     z.object({ role: z.literal(role), result: LensReviewResultSchema })
 
@@ -396,6 +411,10 @@ export const RoleResultSchema = z.discriminatedUnion('role', [
     }),
     lensResult('rules-lens'),
     z.object({ role: z.literal('learner'), result: LearnerResultSchema }),
+    z.object({
+        role: z.literal('story-writer'),
+        result: StoryWriterResultSchema,
+    }),
 ])
 
 export type RoleResult = z.infer<typeof RoleResultSchema>

package/engine/agents/role-turns.ts

@@ -20,4 +20,6 @@ export const MAX_TURNS: Record<AgentRole, number> = {
     'integration-lens': 100,
     'rules-lens': 100,
     learner: 40,
+    // It reads the whole PR's code to walk it (#743).
+    'story-writer': 80,
 }

package/engine/agents/story-writer-instructions.ts

@@ -0,0 +1,69 @@
+/**
+ * The story-writer's instructions (#743): a short opening for a writer with
+ * no shell, then the `/luca-pr-prep` skill's field guide word for word,
+ * the one source of what each story field holds.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * The skill's field guide, next to the engine's source as it ships (see
+ * `skillsDir`): `skills/luca-pr-prep/references/story-format.md`.
+ */
+export const STORY_FORMAT_PATH = join(
+    import.meta.dir,
+    '..',
+    '..',
+    'skills',
+    'luca-pr-prep',
+    'references',
+    'story-format.md'
+)
+
+/** The fields the engine fills in itself; the story-writer leaves them out. */
+export const ENGINE_STORY_FIELDS = [
+    'schema_version',
+    'repo',
+    'pr_number',
+    'pr_url',
+    'title',
+    'base_ref',
+    'head_ref',
+    'head_sha',
+    'base_sha',
+    'written_at',
+    'written_by',
+    'summary.counts',
+]
+
+export const STORY_WRITER = `# Your role: story-writer
+
+You run once, after the run's pull request opened. You write its review story: the guide that walks a reviewer through the change in the order the code runs. You read the code in your folder, the run branch at the pull request's head, with Read, Grep and Glob. You have no shell. You write nothing.
+
+Your prompt holds the pull request, its changed files, its diff (a file left out for size says so: read the file instead), the run's asks (its spec, and each ticket it built with its acceptance criteria), what the run was unsure about, and the repo's rule files, for flags.
+
+The field guide below was written for a writer with a shell. Where this part and the guide disagree, this part wins:
+- You have no shell, so you can't run \`gh\` or \`git\`. Everything you need from git is in your prompt.
+- The engine fills in ${ENGINE_STORY_FIELDS.map((field) => `\`${field}\``).join(', ')}. Leave them out.
+- You can't open the example file or run the helper's \`check\` command the guide points at. Skip those lines. The engine checks your story, and sends every problem back to you.
+- \`summary.feedback_wanted.source\` is \`author\` when its text comes from your prompt's \`What the run was unsure about\` section, and \`guessed\` otherwise. This rule replaces the guide's.
+- A serves ref points only at your prompt's \`The run's asks\`. Its \`label\` is exactly one of two forms, lower case, with nothing before or after: \`spec #12\` for the run's spec, or \`ticket #14, AC2\` for one acceptance criterion of a ticket the run built (the numbers are the issue's and the criterion's). Its \`url\` is that issue's URL, exactly as your prompt gives it. For a ticket ref, \`quote\` is that criterion's exact text; for a spec ref, it is a sentence copied from the spec's body, or null. A change that serves nothing the spec or tickets asked for has \`found: false\`, no refs, and a note that says so.
+
+Your result (structured output): \`summary\` (without \`counts\`), \`map\` and \`stops\`, as the guide describes them.`
+
+/**
+ * The story-writer's own rules, in place of the writers' and reviewers'
+ * (whose results it doesn't share), as the learner has its own.
+ */
+export const STORY_WRITER_RULES = `## Rules for the story-writer
+- Plain code (the engine) drives this run. It fills in the fields it knows, checks your story, and saves it.
+- Never create, edit, or delete a file. The network is off.
+- Finish by giving your structured result. A turn without one counts as failed.`
+
+let format: string | null = null
+
+/** The skill's field guide, read once. */
+export const storyFormat = (): string => {
+    format ??= readFileSync(STORY_FORMAT_PATH, 'utf8')
+    return format
+}

package/engine/config/config-fields.ts

@@ -104,6 +104,16 @@ export const modelsOf = ({ config }: { config: EngineConfig }): ModelsConfig =>
 export const autoRetryOf = ({ config }: { config: EngineConfig }): boolean =>
     config.auto_retry ?? true
 
+/**
+ * Whether a run that opens its pull request writes the PR's story (#743):
+ * the config's `pr_story`, else `true`.
+ *
+ * @example
+ * prStoryOf({ config: { ...config, pr_story: false } }) // false
+ */
+export const prStoryOf = ({ config }: { config: EngineConfig }): boolean =>
+    config.pr_story ?? true
+
 /**
  * The repo's build-cache paths and globs (#721): the config's
  * `build_cache_paths`, else none.

package/engine/config/config-reload.ts

@@ -3,7 +3,7 @@ import omit from 'lodash/omit'
 import reduce from 'lodash/reduce'
 import { z } from 'zod'
 
-import { autoRetryOf, buildCachePathsOf } from './config-fields'
+import { autoRetryOf, buildCachePathsOf, prStoryOf } from './config-fields'
 import type { EngineConfig } from './engine-config'
 
 /**
@@ -35,6 +35,8 @@ import type { EngineConfig } from './engine-config'
  * - `build_cache_paths`: the build caches cloned into each new ticket
  *   worktree (#721). Each new worktree reads it then, so a new value counts
  *   from the next ticket started.
+ * - `pr_story`: whether the run writes its PR's story (#743). Turned off
+ *   on a resume after the story step began, the step just stops.
  */
 export const RELOADED_FIELDS = [
     'prepare',
@@ -46,6 +48,7 @@ export const RELOADED_FIELDS = [
     'leftover_allow',
     'auto_retry',
     'build_cache_paths',
+    'pr_story',
 ] as const
 
 /**
@@ -151,6 +154,12 @@ export const ConfigChangeSchema = z.discriminatedUnion('field', [
         from: z.array(z.string().min(1)),
         to: z.array(z.string().min(1)),
     }),
+    // Never left out: a config without it reads as `true`.
+    z.object({
+        field: z.literal('pr_story'),
+        from: z.boolean(),
+        to: z.boolean(),
+    }),
 ])
 
 export type ConfigChange = z.infer<typeof ConfigChangeSchema>
@@ -217,6 +226,11 @@ export const configChanges = ({
             from: buildCachePathsOf({ config: current }),
             to: buildCachePathsOf({ config: next }),
         },
+        {
+            field: 'pr_story',
+            from: prStoryOf({ config: current }),
+            to: prStoryOf({ config: next }),
+        },
     ]
     return all.filter(({ from, to }) => !isEqual(from, to))
 }
@@ -261,6 +275,8 @@ const applyChange = ({
             return { ...config, auto_retry: change.to }
         case 'build_cache_paths':
             return { ...config, build_cache_paths: change.to }
+        case 'pr_story':
+            return { ...config, pr_story: change.to }
     }
 }
 

package/engine/config/engine-config-schema.ts

@@ -417,6 +417,12 @@ export const EngineConfigSchema = z.object({
      * written before it may lack it (`buildCachePathsOf`).
      */
     build_cache_paths: z.array(BuildCachePathSchema).default([]).optional(),
+    /**
+     * Whether a run that opens its pull request writes the PR's story
+     * (#743). Left out, `true`; a config written before it may lack it
+     * (`prStoryOf`).
+     */
+    pr_story: z.boolean().default(true).optional(),
 })
 
 export type EngineConfig = z.infer<typeof EngineConfigSchema>

package/engine/config/engine-config.ts

@@ -27,6 +27,7 @@ export {
     modelsOf,
     prepareConcurrencyOf,
     prepareTimeoutOf,
+    prStoryOf,
     testTimeoutOf,
 } from './config-fields'
 export {

package/engine/core/decide-limits-helpers.ts

@@ -0,0 +1,37 @@
+import { decide } from './decide'
+
+import type { JournalEntry } from '../journal/journal-record'
+import {
+    agentStarted,
+    intakePassed,
+    practiceTicket,
+    runBranchCreated,
+    ticketBuilt,
+    withInstalls,
+} from '../testing/build-fixtures'
+import { recordsFrom } from '../testing/intake-fixtures'
+
+/**
+ * Helpers shared by the tests of the decision step around plan limits and
+ * usage (`decide-limits.test.ts` and `decide-limits-usage.test.ts`).
+ */
+
+export const TICKET = practiceTicket({ number: 11 })
+
+/** Decide on a run with one ticket (#11) and these entries after intake. */
+export const decideAfter = (entries: JournalEntry[]) =>
+    decide({
+        records: recordsFrom({
+            entries: [
+                ...intakePassed({ tickets: [TICKET] }),
+                ...withInstalls({ entries }),
+            ],
+        }),
+    })
+
+/** Ticket #11 up to its test-writer's launch, which has not finished. */
+export const testWriterRunning = (): JournalEntry[] => [
+    runBranchCreated(),
+    ...ticketBuilt({ ticket: 11 }).slice(0, 2),
+    agentStarted({ ticket: 11, role: 'test-writer' }),
+]

package/engine/core/decide-many-tickets-helpers.ts

@@ -0,0 +1,84 @@
+import { decideSteps } from './decide'
+
+import type { TicketSnapshot } from '../intake/intake-schemas'
+import type { JournalEntry } from '../journal/journal-record'
+import {
+    agentStarted,
+    commitMade,
+    gatesRun,
+    implemented,
+    intakePassed,
+    joinClashed,
+    leftoverScan,
+    practiceTicket,
+    reviewed,
+    runBranchCreated,
+    SESSIONS,
+    ticketApproved,
+    ticketRebased,
+    withInstalls,
+} from '../testing/build-fixtures'
+import { recordsFrom } from '../testing/intake-fixtures'
+
+/**
+ * Helpers shared by the tests of the decision step for many tickets in one
+ * run (`decide-many-tickets.test.ts` and `decide-many-tickets-clash.test.ts`).
+ */
+
+export const SUM = practiceTicket({ number: 11, title: 'Add sum' })
+export const PRODUCT = practiceTicket({ number: 12, title: 'Add product' })
+export const AVERAGE = practiceTicket({
+    number: 13,
+    title: 'Add average',
+    blockers: [11, 12],
+})
+
+/** Every action that can run now, on a run with these tickets and entries. */
+export const stepsAfter = ({
+    tickets,
+    entries,
+}: {
+    tickets: TicketSnapshot[]
+    entries: JournalEntry[]
+}) =>
+    decideSteps({
+        records: recordsFrom({
+            entries: [
+                ...intakePassed({ tickets }),
+                ...withInstalls({ entries }),
+            ],
+        }),
+    })
+
+/** The same, on a run with #11 and #12 only. */
+export const twoSteps = (entries: JournalEntry[]) =>
+    stepsAfter({ tickets: [SUM, PRODUCT], entries })
+
+/** The same, on a run with #11 only. */
+export const oneSteps = (entries: JournalEntry[]) =>
+    stepsAfter({ tickets: [SUM], entries })
+
+/** #11 approved, then its join clashed. */
+export const clashed = (): JournalEntry[] => [
+    runBranchCreated(),
+    ...ticketApproved({ ticket: 11 }),
+    joinClashed({ ticket: 11 }),
+]
+
+/** #11 rebased after `src/index.ts` clashed. */
+export const codeClash = (): JournalEntry =>
+    ticketRebased({ ticket: 11, cause: 'clash', code: ['src/index.ts'] })
+
+/** After a rebase, the ticket fixed and approved again, up to its green commit. */
+export const fixedOnRunBranch = (): JournalEntry[] => [
+    agentStarted({
+        ticket: 11,
+        role: 'implementer',
+        follow_up_of: SESSIONS.implementer,
+    }),
+    implemented({ ticket: 11 }),
+    gatesRun({ ticket: 11, target: 'ticket', ok: true }),
+    leftoverScan({ ticket: 11, stage: 'green' }),
+    commitMade({ ticket: 11, stage: 'green' }),
+    reviewed({ ticket: 11 }),
+]