@alecsibilia/luca 14.0.0-alpha.3 → 14.0.0-alpha.31

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @alecsibilia/luca
 
+## 14.0.0-alpha.31
+
+No changes in this release.
+
+## 14.0.0-alpha.30
+
+No changes in this release.
+
+## 14.0.0-alpha.29
+
+No changes in this release.
+
+## 14.0.0-alpha.28
+
+No changes in this release.
+
+## 14.0.0-alpha.27
+
+No changes in this release.
+
+## 14.0.0-alpha.26
+
+### Patch Changes
+
+- 075d3a4: Spec: /luca-spec-check, a cold read of a spec by three fresh readers before ready-for-agent ([#678](https://github.com/asibilia/luca-framework/issues/678))
+
+## 14.0.0-alpha.25
+
+No changes in this release.
+
+## 14.0.0-alpha.24
+
+No changes in this release.
+
+## 14.0.0-alpha.23
+
+No changes in this release.
+
+## 14.0.0-alpha.22
+
+No changes in this release.
+
+## 14.0.0-alpha.21
+
+No changes in this release.
+
+## 14.0.0-alpha.20
+
+No changes in this release.
+
+## 14.0.0-alpha.19
+
+No changes in this release.
+
+## 14.0.0-alpha.18
+
+No changes in this release.
+
+## 14.0.0-alpha.17
+
+No changes in this release.
+
+## 14.0.0-alpha.16
+
+No changes in this release.
+
+## 14.0.0-alpha.15
+
+No changes in this release.
+
+## 14.0.0-alpha.14
+
+No changes in this release.
+
+## 14.0.0-alpha.13
+
+No changes in this release.
+
+## 14.0.0-alpha.12
+
+No changes in this release.
+
+## 14.0.0-alpha.11
+
+No changes in this release.
+
+## 14.0.0-alpha.10
+
+No changes in this release.
+
+## 14.0.0-alpha.9
+
+No changes in this release.
+
+## 14.0.0-alpha.8
+
+No changes in this release.
+
+## 14.0.0-alpha.7
+
+No changes in this release.
+
+## 14.0.0-alpha.6
+
+No changes in this release.
+
+## 14.0.0-alpha.5
+
+No changes in this release.
+
+## 14.0.0-alpha.4
+
+No changes in this release.
+
 ## 14.0.0-alpha.3
 
 No changes in this release.

package/README.md

@@ -35,17 +35,21 @@ This is Luca v14, in alpha. Old Luca (v13) is still on npm; see [Coming from v13
 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`.
+5. Write a spec with `/to-spec`, then split it into tickets with `/to-tickets`. Before you add `ready-for-agent`, type `/luca-spec-check <spec number>` in Claude Code: three fresh readers give the spec a cold read and list what an agent would have to guess.
 6. In a Paseo chat, type `/luca-run <spec number>`. The board shows the run in the side panel, and the run ends in one pull request.
 
+If a ticket gets stuck, Luca comments on the spec and waits for your one-word reply. Type `/luca-unstick` in Claude Code or a Paseo chat, in the repo: it reads why, says what to do, and posts the reply once you say yes.
+
+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.
+
 ## Commands
 
 | 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. Inside a git repo, it then runs `luca setup` for that repo. |
+| `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, the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`), and Luca's own `/luca-unstick`, `/luca-retro` and `/luca-spec-check` skills. It asks before turning on Paseo's plugins, and leaves skills you already have alone (it only replaces its own). `--skip-skills` skips the planning 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. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then it reloads the board and says when to run `/reload-skills`. |
+| `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. A run that crashed, with no engine running it, doesn't stop it: upgrade says how to resume it on the new version. Then the version it just installed finishes the job with its own code: it reloads the board, copies its skills (every one it ships, new ones included), 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. |
 
 `init`, `setup`, and `upgrade` end with their part of `luca doctor`'s checks.
@@ -88,6 +92,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`. |
 | `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/client/board-look.ts

@@ -13,7 +13,8 @@ import type {
 
 /**
  * Colors and words shared by the side panel and the chat rows, so both views
- * match. Every color comes from the host theme.
+ * match. Every color comes from the host theme, except the models' own
+ * (`MODEL_COLORS`).
  */
 
 export const MONO = Platform.select({ ios: 'Menlo', default: 'monospace' })
@@ -73,7 +74,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':
@@ -139,6 +144,7 @@ export const statusColor = ({
             return theme.colors.statusDanger
         case 'limit_wait':
         case 'usage_line_wait':
+        case 'network_wait':
             return theme.colors.statusWarning
         case 'starting':
         case 'intake':
@@ -150,6 +156,31 @@ export const statusColor = ({
     }
 }
 
+/**
+ * The models' colors (#630): Opus purple, Sonnet orange, Haiku blue, and
+ * Clef (the decision model) green. Fixed hues that read on light and dark
+ * themes alike: the one exception to "every color from the host theme".
+ */
+export const MODEL_COLORS: ReadonlyMap<string, string> = new Map([
+    ['opus', '#a371f7'],
+    ['sonnet', '#e8833a'],
+    ['haiku', '#3b9fe8'],
+    ['clef', '#3fb950'],
+])
+
+/** Clef's confidence bar: green when sharp, orange when split. */
+export const CONFIDENCE_COLORS = { sharp: '#3fb950', split: '#e3a23b' }
+
+/** A model's color; the engine, or a model the board doesn't know, is muted. */
+export const modelColor = ({
+    model,
+    theme,
+}: {
+    model: string
+    theme: PluginTheme
+}): string =>
+    MODEL_COLORS.get(model.toLowerCase()) ?? theme.colors.foregroundMuted
+
 /** A run status in words. */
 export const statusText = ({ status }: { status: RunStatus }): string => {
     switch (status) {
@@ -165,6 +196,8 @@ export const statusText = ({ status }: { status: RunStatus }): string => {
             return 'limit wait'
         case 'usage_line_wait':
             return 'paused at the usage line'
+        case 'network_wait':
+            return 'Waiting for GitHub to be reachable'
         case 'done':
             return 'done'
         case 'refused':

package/board/client/board-panel-parts.tsx

@@ -0,0 +1,150 @@
+/**
+ * The small pieces the panel's sections share: a fix-loop counter, a running
+ * step with its time, a stage header, a banner, and a section.
+ */
+import type { ReactNode } from 'react'
+
+import { Icon } from '@getpaseo/plugin/client/react-native'
+import { Pressable, Text, View } from 'react-native'
+
+import { useNow } from './board-look'
+import type { Look, Styles } from './board-panel-styles'
+import { CutLine, useCloseBubble } from './one-line'
+
+import {
+    LOOP_CAP,
+    currentStepText,
+    type CurrentStep,
+} from '../shared/board-state'
+
+export const Counter = ({
+    label,
+    value,
+    theme,
+    styles,
+}: { label: string; value: number } & Look) => {
+    const color =
+        value >= LOOP_CAP
+            ? theme.colors.statusDanger
+            : value > 0
+              ? theme.colors.statusWarning
+              : theme.colors.foregroundMuted
+    return (
+        <Text
+            style={[styles.counter, { color, borderColor: color }]}
+            numberOfLines={1}
+        >
+            {label} {value}/{LOOP_CAP}
+        </Text>
+    )
+}
+
+/** A running step with its time, counting up by itself, on one line. */
+export const StepLine = ({
+    step,
+    prefix,
+    at = null,
+    styles,
+}: {
+    step: CurrentStep
+    prefix: string
+    /** A stopped clock (#635), in ms, in place of the ticking one. */
+    at?: number | null
+    styles: Styles
+}) => {
+    const ticking = useNow()
+    const now = at ?? ticking
+    return (
+        <CutLine
+            text={`${prefix}${currentStepText({ step, now })}`}
+            style={styles.muted}
+            styles={styles}
+        />
+    )
+}
+
+export const StageHeader = ({
+    title,
+    hint,
+    icon,
+    count,
+    color,
+    folded,
+    onPress,
+    theme,
+    styles,
+}: {
+    title: string
+    hint: string
+    icon: string
+    count: number
+    color: string
+    folded: boolean | null
+    onPress: (() => void) | null
+} & Look) => {
+    const closeBubble = useCloseBubble()
+    const empty = count === 0
+    const tint = empty ? theme.colors.foregroundMuted : color
+    const content = (
+        <>
+            <Icon name={icon} size={13} color={tint} />
+            <Text style={[styles.stageTitle, { color: tint }]}>
+                {title.toUpperCase()}
+            </Text>
+            <Text style={styles.stageCount}>{count}</Text>
+            {empty || hint === '' ? null : (
+                <Text style={styles.stageHint} numberOfLines={1}>
+                    {hint}
+                </Text>
+            )}
+            <View style={styles.spacer} />
+            {folded === null || empty ? null : (
+                <Icon
+                    name={folded ? 'ChevronRight' : 'ChevronDown'}
+                    size={13}
+                    color={theme.colors.foregroundMuted}
+                />
+            )}
+        </>
+    )
+    const style = [styles.stageHeader, empty ? styles.stageHeaderThin : null]
+    if (!onPress || empty) return <View style={style}>{content}</View>
+    return (
+        <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={`${title}, ${count}. ${folded ? 'Open' : 'Fold'} this stage`}
+            onPress={() => {
+                closeBubble()
+                onPress()
+            }}
+            style={style}
+        >
+            {content}
+        </Pressable>
+    )
+}
+
+export const Banner = ({
+    icon,
+    color,
+    children,
+    styles,
+}: {
+    icon: string
+    color: string
+    children: ReactNode
+    styles: Styles
+}) => (
+    <View style={[styles.banner, { borderColor: color }]}>
+        <Icon name={icon} size={13} color={color} />
+        <Text style={[styles.bannerText, { color }]}>{children}</Text>
+    </View>
+)
+
+export const Section = ({
+    children,
+    styles,
+}: {
+    children: ReactNode
+    styles: Styles
+}) => <View style={styles.block}>{children}</View>

package/board/client/board-panel-stages.ts

@@ -0,0 +1,99 @@
+/**
+ * The stages the panel stacks tickets and lenses in, and the keys of the
+ * cards and stages a person opens or folds.
+ */
+import type { LensState, TicketStage } from '../shared/board-state'
+
+type StackStage = Exclude<TicketStage, 'stuck'>
+
+export const TICKET_STAGES: {
+    stage: StackStage
+    title: string
+    hint: string
+    icon: string
+    folded: boolean
+}[] = [
+    {
+        stage: 'blocked',
+        title: 'Blocked',
+        hint: "waits on a ticket that isn't done",
+        icon: 'Lock',
+        folded: false,
+    },
+    {
+        stage: 'building',
+        title: 'Building',
+        hint: 'the first tests and code',
+        icon: 'Hammer',
+        folded: false,
+    },
+    {
+        stage: 'reviewing',
+        title: 'Reviewing',
+        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',
+        hint: 'joined the run branch',
+        icon: 'CircleCheck',
+        folded: true,
+    },
+    {
+        stage: 'skipped',
+        title: 'Skipped',
+        hint: 'left out of this run, stays open',
+        icon: 'SkipForward',
+        folded: true,
+    },
+]
+
+export const LENS_STAGES: { stage: LensState; title: string; icon: string }[] =
+    [
+        { stage: 'waiting', title: 'Waiting', icon: 'Clock' },
+        { stage: 'reviewing', title: 'Reviewing', icon: 'ScanSearch' },
+        { stage: 'fixing', title: 'Fixing', icon: 'Wrench' },
+        { stage: 'clean', title: 'Clean', icon: 'CircleCheck' },
+    ]
+
+/** A card or stage key. */
+export type Key = string
+
+/** The key of the fold for tickets left out for a person (#499). */
+export const FOR_A_PERSON: Key = 'for_a_person'
+
+export const toggled = ({
+    set,
+    key,
+}: {
+    set: ReadonlySet<Key>
+    key: string
+}): Set<Key> => {
+    const next = new Set(set)
+    if (next.has(key)) next.delete(key)
+    else next.add(key)
+    return next
+}

package/board/client/board-panel-styles.ts

@@ -0,0 +1,223 @@
+/**
+ * The side panel's styles: one `StyleSheet` made from the host theme, and
+ * the `Look` (theme and styles) every piece of the panel takes.
+ */
+import type { PluginTheme } from '@getpaseo/plugin'
+import { StyleSheet } from 'react-native'
+
+import { DIMMED, MONO } from './board-look'
+
+export const makeStyles = ({
+    theme,
+    compact,
+}: {
+    theme: PluginTheme
+    compact: boolean
+}) => {
+    const { colors } = theme
+    return StyleSheet.create({
+        screen: { flex: 1, backgroundColor: colors.surface0 },
+        content: { padding: compact ? 10 : 16, gap: 8 },
+        /** Fills the scroll area, so a tap on its blank part lands too. */
+        fill: { flexGrow: 1 },
+        /** The cards' scroll area, above the pinned status bar. */
+        scroll: { flex: 1 },
+        /** The status bar, pinned at the bottom of the panel. */
+        statusBar: {
+            flexShrink: 0,
+            gap: 4,
+            borderTopColor: colors.border,
+            borderTopWidth: 1,
+            backgroundColor: colors.surface1,
+            paddingHorizontal: compact ? 10 : 16,
+            paddingVertical: 5,
+        },
+        row: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            flexWrap: 'wrap',
+            gap: compact ? 6 : 10,
+        },
+        /** A row that stays on one line: its cut lines give way. */
+        line: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap: compact ? 6 : 10,
+        },
+        /** A part that never shrinks or gets cut: a number, tag or time. */
+        fixed: { flexShrink: 0 },
+        /** What holds a cut line: it gives way, down to nothing. */
+        cut: { flexShrink: 1, minWidth: 0 },
+        /** The bubble a tap on a cut line opens, with its full text. */
+        bubble: {
+            color: colors.foreground,
+            backgroundColor: colors.surface2,
+            borderColor: colors.border,
+            borderWidth: 1,
+            borderRadius: 6,
+            paddingHorizontal: 8,
+            paddingVertical: 5,
+            fontSize: 12,
+        },
+        title: { color: colors.foreground, fontSize: 16, fontWeight: '700' },
+        spacer: { flex: 1 },
+        text: { color: colors.foreground, fontSize: 13 },
+        muted: { color: colors.foregroundMuted, fontSize: 12 },
+        mono: { color: colors.foregroundMuted, fontSize: 12, fontFamily: MONO },
+        small: { color: colors.foregroundMuted, fontSize: 11 },
+        pill: {
+            flexShrink: 0,
+            borderWidth: 1,
+            borderRadius: 999,
+            paddingHorizontal: 7,
+            paddingVertical: 1,
+            fontSize: 11,
+            fontWeight: '700',
+        },
+        chip: {
+            borderWidth: 1,
+            borderColor: colors.border,
+            borderRadius: 6,
+            paddingHorizontal: 8,
+            paddingVertical: 3,
+        },
+        chipOn: {
+            borderColor: colors.accent,
+            backgroundColor: colors.surface2,
+        },
+        banner: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap: 6,
+            borderWidth: 1,
+            borderRadius: 6,
+            paddingHorizontal: 8,
+            paddingVertical: 5,
+        },
+        bannerText: { fontSize: 12, flexShrink: 1 },
+        block: { gap: 6 },
+        stageHeader: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap: 6,
+            paddingVertical: 4,
+            paddingHorizontal: 6,
+            borderRadius: 6,
+        },
+        stageHeaderThin: { paddingVertical: 1, opacity: DIMMED },
+        stageTitle: { fontSize: 12, fontWeight: '700', letterSpacing: 1 },
+        stageCount: {
+            color: colors.foregroundMuted,
+            fontSize: 12,
+            fontFamily: MONO,
+        },
+        stageHint: {
+            color: colors.foregroundMuted,
+            fontSize: 11,
+            flexShrink: 1,
+        },
+        stageBody: { gap: 6, paddingLeft: compact ? 0 : 8 },
+        card: {
+            backgroundColor: colors.surface1,
+            borderColor: colors.border,
+            borderWidth: 1,
+            borderRadius: 8,
+            paddingHorizontal: compact ? 8 : 10,
+            paddingVertical: compact ? 7 : 8,
+            gap: 5,
+        },
+        cardStuck: { borderColor: colors.statusDanger, borderLeftWidth: 4 },
+        cardPressed: { backgroundColor: colors.surface2 },
+        cardTop: { flexDirection: 'row', alignItems: 'center', gap: 6 },
+        number: {
+            flexShrink: 0,
+            color: colors.foregroundMuted,
+            fontSize: 12,
+            fontWeight: '700',
+            fontFamily: MONO,
+        },
+        cardTitle: {
+            color: colors.foreground,
+            fontSize: 13,
+            fontWeight: '600',
+            flexShrink: 1,
+        },
+        tag: {
+            flexShrink: 0,
+            color: colors.foregroundMuted,
+            borderColor: colors.border,
+            borderWidth: 1,
+            borderRadius: 4,
+            paddingHorizontal: 4,
+            fontSize: 10,
+        },
+        /** Clef's confidence bar, and its part filled to the confidence. */
+        confidence: {
+            flexShrink: 0,
+            width: 28,
+            height: 5,
+            borderRadius: 3,
+            overflow: 'hidden',
+            backgroundColor: colors.surface2,
+        },
+        confidenceFill: { height: 5 },
+        /** A running helper's line (#636), its left edge in its model's colour. */
+        helperLine: { borderLeftWidth: 2, paddingLeft: 6 },
+        dots: { flexDirection: 'row', alignItems: 'center', flexShrink: 0 },
+        dotCell: { flexDirection: 'row', alignItems: 'center' },
+        link: { width: compact ? 7 : 10, height: 2 },
+        dot: { width: 8, height: 8, borderRadius: 4, borderWidth: 1.5 },
+        dotCurrent: { width: 12, height: 12, borderRadius: 6, borderWidth: 2 },
+        dotSkip: { borderStyle: 'dashed' },
+        stepLabel: { fontSize: 12, fontWeight: '600', marginLeft: 6 },
+        /** A waiting card's amber bar, where a heartbeat would be. */
+        waitBar: {
+            flexShrink: 0,
+            width: 28,
+            height: 4,
+            borderRadius: 2,
+            opacity: 0.8,
+        },
+        /** A busy card's heartbeat, and each of its bars, standing on the bottom. */
+        heartbeat: {
+            flexDirection: 'row',
+            alignItems: 'flex-end',
+            flexShrink: 0,
+            height: 14,
+            gap: 1,
+        },
+        heartbeatBar: { width: 2, borderRadius: 1 },
+        counter: {
+            flexShrink: 0,
+            borderWidth: 1,
+            borderRadius: 5,
+            paddingHorizontal: 5,
+            fontSize: 11,
+            fontFamily: MONO,
+        },
+        detail: {
+            gap: 3,
+            borderTopColor: colors.border,
+            borderTopWidth: 1,
+            paddingTop: 5,
+        },
+        label: {
+            color: colors.foregroundMuted,
+            fontSize: 12,
+            fontWeight: '700',
+        },
+        rule: { height: 1, backgroundColor: colors.border, marginVertical: 4 },
+        reviewTitle: {
+            color: colors.foreground,
+            fontSize: 14,
+            fontWeight: '700',
+        },
+        prLink: { color: colors.accent, fontSize: 12 },
+    })
+}
+
+type MakeStyles = typeof makeStyles
+
+export type Styles = ReturnType<MakeStyles>
+
+export type Look = { theme: PluginTheme; styles: Styles }