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

package/engine/tracker/in-memory-tracker.ts

@@ -15,7 +15,7 @@ export type InMemoryPullRequest = PullRequestRequest & OpenedPullRequest
 
 /** An in-memory tracker, plus what tests need to look inside it. */
 export type InMemoryTracker = Tracker & {
-    /** Every comment's body on an issue, oldest first. */
+    /** Every comment's body on an issue or a pull request, oldest first. */
     commentsOn: (args: { number: number }) => string[]
     /** A person comments on an issue, as on the tracker; returns the comment's id. */
     addComment: (args: {
@@ -84,7 +84,8 @@ export const createInMemoryTracker = ({
         author: string
         body: string
     }): number => {
-        find(number)
+        // A pull request takes comments too, as on GitHub.
+        if (!pulls.some((pull) => pull.number === number)) find(number)
         lastCommentId += 1
         const comment = { id: lastCommentId, author, body }
         comments.set(number, [...(comments.get(number) ?? []), comment])
@@ -110,8 +111,11 @@ export const createInMemoryTracker = ({
                 (comments.get(number) ?? []).filter(({ id }) => id > since_id)
             ),
         addComment: (args) => post(args),
-        addLabel: async ({ number, label }) =>
-            setLabels(number, uniq([...find(number).labels, label])),
+        // A label the repo lacks is created first, as on GitHub (#500).
+        addLabel: async ({ number, label }) => {
+            if (!labels.includes(label)) labels.push(label)
+            setLabels(number, uniq([...find(number).labels, label]))
+        },
         removeLabel: async ({ number, label }) =>
             setLabels(
                 number,

package/engine/tracker/tracker.ts

@@ -57,27 +57,43 @@ export type Tracker = {
     listSubTickets: (args: { spec_number: number }) => Promise<TrackerIssue[]>
     /** Reads any issue, such as a blocker outside the spec. `null` if missing. */
     readIssue: (args: { number: number }) => Promise<TrackerIssue | null>
-    /** Posts a comment on an issue, and returns the new comment's id. */
+    /**
+     * Posts a comment on an issue or a pull request, and returns the new
+     * comment's id.
+     */
     comment: (args: { number: number; body: string }) => Promise<{ id: number }>
     /** An issue's comments with an id above `since_id`, oldest first. */
     listComments: (args: {
         number: number
         since_id: number
     }) => Promise<TrackerComment[]>
-    /** Adds a label to an issue. Adding a label it already has does nothing. */
+    /**
+     * Adds a label to an issue. Adding a label it already has does nothing. A
+     * label the repo lacks is created first, as `labelDefinition` describes
+     * it (#500).
+     */
     addLabel: (args: { number: number; label: string }) => Promise<void>
-    /** Removes a label from an issue. Removing a missing label does nothing. */
+    /**
+     * Removes a label from an issue. Removing a label the issue or the repo
+     * lacks does nothing.
+     */
     removeLabel: (args: { number: number; label: string }) => Promise<void>
     /**
      * Closes an issue as completed, such as a ticket whose work was already
      * done (#484). Closing a closed issue does nothing.
      */
     closeIssue: (args: { number: number }) => Promise<void>
-    /** Opens a pull request from `head` into `base`. */
+    /**
+     * Opens a pull request from `head` into `base`. Throws a `TrackerError`
+     * when the tracker couldn't open it (such as a failed `gh pr create`),
+     * which the PR step makes a stuck run the owner can `retry` (#508).
+     */
     openPullRequest: (args: PullRequestRequest) => Promise<OpenedPullRequest>
     /**
-     * The open pull request from branch `head`, or `null`: a redo after a
-     * crash adopts the PR its first try opened.
+     * The open pull request from branch `head` of the repo itself (never a
+     * fork's), or `null`: the PR step reuses one, such as the PR a try
+     * opened before a crash or a failure. Throws a `TrackerError` when the
+     * tracker couldn't list them.
      */
     findOpenPullRequest: (args: {
         head: string
@@ -97,9 +113,41 @@ export type Tracker = {
     issueLinks: () => Promise<{ sub_issues: boolean; dependencies: boolean }>
 }
 
+/**
+ * A tracker call that failed, such as a `gh` command that exited non-zero.
+ * The PR step makes one a stuck run (#508); any other error is a crash.
+ */
+export class TrackerError extends Error {
+    override name = 'TrackerError'
+}
+
+/** A failed `gh` call, in the words `TrackerError`s from `gh` use. */
+const GH_FAILED = /\bgh \w+ \w+`? failed\b/
+
+/**
+ * Whether `error` is a failed tracker call: a `TrackerError`, or a plain
+ * error worded like one from `gh` ("gh pr create failed ..."), as a tracker
+ * wrapped around the GitHub one may throw.
+ *
+ * @example
+ * isTrackerFailure(new TrackerError('gh pr create failed')) // true
+ * isTrackerFailure(new Error('The engine crashed.')) // false
+ */
+export const isTrackerFailure = (error: unknown): boolean =>
+    error instanceof TrackerError ||
+    (error instanceof Error && GH_FAILED.test(error.message))
+
 /** The label a ticket needs before intake lets a run build it. */
 export const READY_LABEL = 'ready-for-agent'
 
+/**
+ * The label on a ticket only a person can do (#499), such as renaming the
+ * repo or shipping after a hands-on check. Intake leaves it out of the run,
+ * with the tickets that wait on it, and never comments on it or relabels
+ * it. A ticket with both this and `READY_LABEL` counts as for a person.
+ */
+export const HUMAN_LABEL = 'ready-for-human'
+
 /**
  * The label that makes a ticket a refactor ticket: it changes how the code is
  * shaped, not what it does, so it skips the test-writer and the red check.
@@ -122,3 +170,80 @@ export const RELEASE_LABELS = [
     'release:major',
     'release:none',
 ] as const
+
+/**
+ * A label as the engine creates it in a repo: `luca setup` does, and so
+ * does `addLabel` when the repo lacks it.
+ */
+export type LabelDefinition = {
+    name: string
+    /** Six hex digits, without `#`. */
+    color: string
+    description: string
+}
+
+/** The labels a run needs, with what they're for. */
+export const RUN_LABELS: LabelDefinition[] = [
+    {
+        name: READY_LABEL,
+        color: '0e8a16',
+        description: 'Ready for a Luca run',
+    },
+    {
+        // A run leaves these, and the tickets waiting on them, out (#499).
+        name: HUMAN_LABEL,
+        color: 'c5def5',
+        description: 'Needs a person, not an agent',
+    },
+    {
+        name: REFACTOR_LABEL,
+        color: '5319e7',
+        description: 'Changes shape, not behavior: no new tests',
+    },
+    {
+        name: NEEDS_INFO_LABEL,
+        color: 'd93f0b',
+        description: 'Luca needs more detail before it can build this',
+    },
+]
+
+/** The version-bump labels a repo with changesets gets, one per bump. */
+export const RELEASE_LABEL_DEFINITIONS: Record<
+    (typeof RELEASE_LABELS)[number],
+    LabelDefinition
+> = {
+    'release:patch': {
+        name: 'release:patch',
+        color: 'c2e0c6',
+        description: "A patch bump for this spec's changeset (the default)",
+    },
+    'release:minor': {
+        name: 'release:minor',
+        color: 'fbca04',
+        description: "A minor bump for this spec's changeset",
+    },
+    'release:major': {
+        name: 'release:major',
+        color: 'b60205',
+        description: "A major bump for this spec's changeset",
+    },
+    'release:none': {
+        name: 'release:none',
+        color: 'ededed',
+        description: 'No version bump: an empty changeset',
+    },
+}
+
+/**
+ * How the engine creates the label `name` in a repo that lacks it: as
+ * `luca setup` would, or plain grey with no description for a label Luca
+ * doesn't define.
+ *
+ * @example
+ * labelDefinition({ name: 'needs-info' }).color // 'd93f0b'
+ * labelDefinition({ name: 'odd' }) // { name: 'odd', color: 'ededed', description: '' }
+ */
+export const labelDefinition = ({ name }: { name: string }): LabelDefinition =>
+    [...RUN_LABELS, ...Object.values(RELEASE_LABEL_DEFINITIONS)].find(
+        (label) => label.name === name
+    ) ?? { name, color: 'ededed', description: '' }

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.2",
+    "version": "14.0.0-alpha.21",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",
@@ -24,6 +24,7 @@
     "files": [
         "engine/",
         "board/",
+        "skills/",
         "README.md",
         "LICENSE",
         "CHANGELOG.md"

package/skills/luca-retro/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: luca-retro
+description: Looks back at a finished Luca run and suggests changes to the agents' environment, not the code, so the next run goes better. It reads the run's journal, ranks what went wrong (most serious first), and says for each one the change to make and where: a check to add, a line for the repo's rules file, an instruction to delete, missing information, waste, or a Luca bug. Once the owner picks findings by number, it opens a GitHub issue for each, after a yes. Use it for `/luca-retro [run id ...]`, and whenever someone asks for a retro, what went wrong in the run, how to stop this happening again, or the lessons from a run, even if they don't name the skill.
+argument-hint: "[run id ...]"
+---
+
+# Look back at a Luca run
+
+A retro changes the agents' environment, not the code: when an agent got something wrong, ask what would have stopped it. A mistake a machine can spot gets a check (a lint rule, a gate, a guard, a CI job). A judgement call gets one line in the repo's rules file. An instruction that changed nothing gets deleted. Run by hand after a run, so the rules get shorter over time, not longer.
+
+You were given: $ARGUMENTS
+
+That is zero or more run ids. Talk to the owner in plain words: short sentences, no jargon they didn't use first.
+
+## 1. Read the run
+
+Run the helper from the repo's folder. It only reads.
+
+```bash
+bun ~/.claude/skills/luca-retro/scripts/retro-summary.ts [run id ...]
+```
+
+- No run id: it sums up this repo's newest finished run (one that opened its PR, was stopped, or had nothing to do), found from the main checkout, any of its worktrees, or a subfolder. If that isn't the one the owner means, ask.
+- Several run ids: it sums up each, then lists the patterns that repeat across them. A repeat ranks higher.
+- It prints the run's spec, repo, Luca versions, and how it ended; then what got stuck and how long the owner took to reply, fix loops that hit their cap, leftover scan hits, agents out of turns, "No open agent session" failures, decision model calls that failed, checks and tests that failed again and again, setup changes agents asked for, joins that clashed, replies, the agents' assumptions, the findings fixers declined, slow steps, and tokens. Every line names its journal seq (`seq 123`).
+
+The journal is all there is: agents run without saved sessions, so there are no transcripts. To read one record in full: `jq -c 'select(.seq == 123)' ~/.local/state/luca/runs/<run id>/journal.jsonl` (or under `$LUCA_RUNS_DIR`). The records are JSON lines: `seq`, `time`, `kind`, `ticket`, `role`, `content`.
+
+When a finding needs it, look (read only) at what the agents were given in the run's repo: the rule files listed in `.luca/config.json` (`rule_files`, also `test_file_patterns` and `test_setup_files`), `AGENTS.md` or `CLAUDE.md`, the glossary and ADRs, the lint config, and the CI config. Check whether a rule already covers the mistake before suggesting one.
+
+## 2. Rank the findings
+
+List them most serious first: what cost the most time, tokens, or owner replies, and what repeats. For each:
+
+1. **What happened**, with evidence: seqs, tickets, counts. Say it plainly. Cite a journal record as `seq <n>`, never `#<n>`: on GitHub, `#<n>` links to an unrelated issue. Tickets, PRs, and issues keep `#<n>`.
+2. **Its bucket**, one of six:
+   - **(a) Check to add**: a lint rule, a gate, a guard, or a CI job, for a mistake a machine can spot.
+   - **(b) Rules line**: one line for the repo's rules file, for a judgement call.
+   - **(c) Delete**: an instruction that changed nothing, or one so long it hid the rest.
+   - **(d) Missing information**: a glossary word, an ADR, a setup step the agents had to guess (their assumptions show these).
+   - **(e) Waste**: tools or tokens spent for nothing, such as agents out of turns, steps far slower than the rest, or calls that always fail.
+   - **(f) Luca bug**: the engine itself went wrong. It goes to `asibilia/luca-framework`, not the repo.
+3. **The change**, and where: the file and the words, or the check and what it catches.
+
+Prefer (a) over (b) when a check can catch it: a check works every time, a rule only when read. Prefer deleting over adding. Leave out what happened once and can't happen again.
+
+Some signs, from the helper's sections:
+
+- The same stuck reason (such as `leftovers_found`) again and again: a rule or a check, or a Luca bug when the engine was wrong to block it.
+- A `setup_change_needed`: the repo's setup was missing something every ticket like it will need.
+- Agents out of turns, or "No open agent session" failures: often (e) or (f).
+- A `jev_failed` on every call, or a `decision_model_off`: missing or turned-down Cloudflare credentials in `~/.config/luca/.env`, (e).
+- One test failing in many gates: a flaky or build-bound test, (a) or (f).
+- Many assumptions about the same thing: (d).
+- A finding declined with `wont_fix` for a reason the run can't change (a role can't write a file): (f) or (b).
+
+## 3. Stop
+
+Show the ranked list, numbered, and stop. Nothing happens until the owner picks findings by number.
+
+## 4. Open an issue for each pick
+
+For each finding the owner picked:
+
+1. Check for one already open or closed: `gh issue list --repo <owner/repo> --search "<a few words>" --state all`. If one fits, link it instead of opening a new one.
+2. Otherwise show the issue's exact title and body, and the repo it goes to: Luca bugs to `asibilia/luca-framework`, the rest to the run's repo (the "Repo" line). Put the evidence in the body: the run id, the seqs (as `seq <n>`), the Luca version. Cite a ticket, PR, or issue of another repo as `owner/repo#<n>`, so it links to the right place; a bare `#<n>` links to the repo the issue is in.
+3. Wait for a yes, then open it: `gh issue create --repo <owner/repo> --title "<title>" --body "<body>"`. Say the link.
+
+## What not to do
+
+- Never edit code or rule files, and never commit. The issue says what to change; a person or a later run does it.
+- Never open an issue without the owner's yes.
+- Never run on your own: only when the owner asks.
+- Never edit the journal. It is the engine's.