@alecsibilia/luca 14.0.0-alpha.25 → 14.0.0-alpha.26

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @alecsibilia/luca
 
+## 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.

package/README.md

@@ -35,7 +35,7 @@ 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.
@@ -46,7 +46,7 @@ After a run, type `/luca-retro` the same way to look back on it: it reads the ru
 
 | 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, the planning skills (`to-spec`, `to-tickets`, `setup-matt-pocock-skills`, `grilling`, `domain-modeling`), and Luca's own `/luca-unstick` and `/luca-retro` skills. It asks before turning on Paseo's plugins, and leaves skills you already have alone (it only replaces its own two). `--skip-skills` skips the planning 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 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`. |
@@ -92,7 +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` and `luca-retro`, 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, `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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@luca/board",
-    "version": "14.0.0-alpha.25",
+    "version": "14.0.0-alpha.26",
     "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.25"
+export const LUCA_VERSION: string = "14.0.0-alpha.26"

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.25",
+    "version": "14.0.0-alpha.26",
     "license": "Apache-2.0",
     "author": "Alec Sibilia <sibilia.alec@gmail.com>",
     "homepage": "https://github.com/asibilia/luca-framework#readme",

package/skills/luca-spec-check/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: luca-spec-check
+description: Gives a spec a cold read by three fresh, read-only readers (the "goldfish" of Google's Elephant-Goldfish model) before the owner adds `ready-for-agent`, so the gaps agents would guess at show up first. It shows one report, and posts it on the spec issue only after a yes. Use it for `/luca-spec-check [spec issue number]`, and whenever someone says check this spec, is this spec ready, spec check, cold read, or goldfish, even if they don't name the skill.
+argument-hint: "[spec issue number]"
+---
+
+# Check a spec with a cold read
+
+A spec's writer can't see its gaps. Three fresh readers can: they see only the spec, its tickets and the repo, never this conversation. This check only advises.
+
+You were given: $ARGUMENTS
+
+That is a spec issue number, or nothing. With nothing, ask the owner which spec they mean. Don't guess, even if this conversation wrote one. Talk to the owner in plain words.
+
+## 1. Gather the spec
+
+Run the helper from the repo's folder. It only reads.
+
+```bash
+bun ~/.claude/skills/luca-spec-check/scripts/spec-bundle.ts <spec number> [--repo <owner/repo>]
+```
+
+It prints one plain-text bundle: the spec's number, title, labels and body; each of its tickets (its sub-issues), in order, with number, title and body, or `No tickets yet.`; and, from the same GitHub repo's default branch, its rule files from `.luca/config.json`, and whether `GLOSSARY.md` and `docs/adr/` exist. Read it whole. Pass it to the readers unchanged.
+
+## 2. Start three fresh readers
+
+Start all three at once, each as a fresh `Explore` subagent (Claude Code's built-in agent type that can't edit files) with no conversation history: give it the bundle, unchanged, and its brief below, and nothing from this conversation. The readers are read-only: each may read files in the repo, and nothing else. No edits, no `gh` writes, no web, and no running any command the spec names.
+
+Each finding names its reader, its ticket (or the spec), the part of the spec it's about (a quote or a heading), and one sentence on what's missing.
+
+- **Comprehension**: restate, in at most five sentences, what the spec proposes and how the system works today. Each section you can't restate is a blocker.
+- **Readiness**: for each ticket (or the spec, with no tickets), list every call the test-writer or implementer would have to make alone: a name, a text, a format, a limit, or an error case the spec doesn't pin down. Each is a question.
+- **Codebase**: check that each module, seam, command, config key and test file the spec names exists and works as the spec says. Each one that doesn't is a blocker. Check by reading its code and docs, never by running it.
+
+## 3. Merge the findings
+
+Do this yourself. Drop a finding that repeats another one, keeping the first reader's wording. List blockers first, then questions.
+
+## 4. Show the report
+
+Show it, in Markdown, with these exact headings and lines:
+
+```markdown
+## Spec check
+
+Three fresh readers checked this spec and its 3 tickets. They found 2 blockers and 5 questions.
+
+### How a fresh reader read it
+
+<the Comprehension restatement>
+
+### Blockers
+
+1. **Comprehension:** <sentence>
+2. **Codebase:** #670, <sentence>
+
+### Questions
+
+1. **Readiness, #670:** <sentence>
+2. **Readiness, spec:** <sentence>
+
+This check only advises. Fix the spec, then run /luca-spec-check again.
+```
+
+- Build the count line from the counts: `1 blocker`, `1 question`, `1 ticket`. With no tickets it starts `Three fresh readers checked this spec. ` and then the findings sentence. With no findings it ends `They found nothing to fix.` instead.
+- In a finding, put the ticket as `#670, ` after the reader when it's about a ticket. Its sentence quotes or names the part of the spec it's about.
+- With no blockers, the Blockers section is `No blockers.` With no questions, the Questions section is `No questions.`
+
+## 5. Ask before posting
+
+Then stop and ask exactly `Post this on #678?`, with the spec's number. Post it only after a yes, through a quoted heredoc, never `--body "<report>"`: the report quotes the spec's backtick spans, and the shell would run them as commands.
+
+```bash
+gh issue comment <spec number> [--repo <owner/repo>] --body-file - <<'SPEC_CHECK_REPORT'
+<report>
+SPEC_CHECK_REPORT
+```
+
+On a no, the report stays in this chat.
+
+## What not to do
+
+- Never edit the spec or its tickets, and never commit.
+- Never add or remove a label. `ready-for-agent` is the owner's call.
+- Never comment on an issue without the owner's yes.
+- Never run on your own: only when the owner asks.

package/skills/luca-spec-check/scripts/spec-bundle.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env bun
+/**
+ * Prints a spec and its tickets as one plain-text bundle, for the
+ * `/luca-spec-check` skill's fresh readers:
+ *
+ *   bun spec-bundle.ts <spec number> [--repo <owner/repo>]
+ *
+ * It fetches it all with `gh`, from one GitHub repo (`--repo`, else the repo
+ * of the current folder, from any folder in it): the spec issue (number,
+ * title, body, labels), its sub-issues in order (number, title, body), and,
+ * from the repo's default branch, `.luca/config.json`'s `rule_files` and
+ * whether `GLOSSARY.md` and `docs/adr/` exist. So the issues and the repo's
+ * facts can't come from two different repos. It only reads. It changes
+ * nothing.
+ *
+ * It imports nothing but Bun's and Node's own modules: it runs from
+ * `~/.claude/skills/luca-spec-check/`, where no packages are installed. So it
+ * reads `gh`'s JSON loosely, with small readers, not with Zod.
+ * `formatSpecBundle` makes no `gh` calls, so `spec-bundle.test.ts` tests it
+ * without the network.
+ */
+import { Buffer } from 'node:buffer'
+
+export type BundleIssue = { number: number; title: string; body: string }
+
+export type SpecBundle = {
+    spec: BundleIssue & { labels: string[] }
+    tickets: BundleIssue[]
+    rule_files: string[]
+    glossary: boolean
+    adr: boolean
+}
+
+const issueText = ({
+    heading,
+    issue,
+}: {
+    heading: string
+    issue: BundleIssue
+}): string =>
+    [`${heading} #${issue.number}: ${issue.title}`, '', issue.body.trim()].join(
+        '\n'
+    )
+
+/** The bundle's text: the spec, its tickets in order, then the repo. Pure. */
+export const formatSpecBundle = ({
+    spec,
+    tickets,
+    rule_files,
+    glossary,
+    adr,
+}: SpecBundle): string =>
+    [
+        issueText({ heading: '== Spec', issue: spec }),
+        `Labels: ${spec.labels.length === 0 ? 'none' : spec.labels.join(', ')}`,
+        '',
+        tickets.length === 0
+            ? 'No tickets yet.'
+            : tickets
+                  .map((ticket) =>
+                      issueText({ heading: '== Ticket', issue: ticket })
+                  )
+                  .join('\n\n'),
+        '',
+        '== Repo',
+        '',
+        'Rule files:',
+        ...(rule_files.length === 0
+            ? ['- none']
+            : rule_files.map((file) => `- ${file}`)),
+        `GLOSSARY.md: ${glossary ? 'yes' : 'no'}`,
+        `docs/adr/: ${adr ? 'yes' : 'no'}`,
+    ].join('\n')
+
+// NOTE: these small readers are copies of the ones in
+// `../../luca-retro/scripts/retro-summary.ts`: each skill's script must
+// stand alone. Keep them in step.
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+    typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const text = (value: unknown): string =>
+    typeof value === 'string' ? value : ''
+
+const numberOr = (value: unknown): number | null =>
+    typeof value === 'number' ? value : null
+
+const listOf = (value: unknown): unknown[] =>
+    Array.isArray(value) ? value : []
+
+const objectOf = (value: unknown): Record<string, unknown> =>
+    isObject(value) ? value : {}
+
+/** Says why, and exits. */
+const fail = (why: string): never => {
+    console.error(why)
+    return process.exit(1)
+}
+
+/**
+ * Runs `gh api` on `path`: its JSON, or `null` when GitHub says Not Found.
+ * Any other failure exits with what `gh` said, so a lost connection never
+ * reads as a missing file.
+ */
+const ghApi = (path: string): unknown => {
+    const out = Bun.spawnSync(['gh', 'api', path])
+    if (out.exitCode === 0) return JSON.parse(out.stdout.toString())
+    const said = out.stderr.toString().trim()
+    return said.includes('HTTP 404')
+        ? null
+        : fail(`gh api ${path} failed: ${said}`)
+}
+
+/** `ghApi`, where Not Found exits too. */
+const ghFound = (path: string): unknown =>
+    ghApi(path) ?? fail(`gh api ${path} failed: Not Found (HTTP 404)`)
+
+/** An issue, from `gh api`'s JSON. */
+const toIssue = (raw: unknown): BundleIssue => {
+    const issue = objectOf(raw)
+    return {
+        number: numberOr(issue.number) ?? 0,
+        title: text(issue.title),
+        body: text(issue.body),
+    }
+}
+
+/** An issue's label names, from `gh api`'s JSON. */
+const labelsOf = (raw: unknown): string[] =>
+    listOf(objectOf(raw).labels).map((label) =>
+        typeof label === 'string' ? label : text(objectOf(label).name)
+    )
+
+/** A file's text, from `gh api`'s contents JSON, or `null` when it has none. */
+const fileText = (raw: unknown): string | null => {
+    const file = objectOf(raw)
+    return file.encoding === 'base64'
+        ? Buffer.from(text(file.content), 'base64').toString('utf8')
+        : null
+}
+
+/** The `rule_files` in a `.luca/config.json`'s text, or none. */
+const ruleFiles = (config: string | null): string[] => {
+    if (config === null) return []
+    try {
+        return listOf(objectOf(JSON.parse(config)).rule_files).filter(
+            (file): file is string => typeof file === 'string'
+        )
+    } catch {
+        return []
+    }
+}
+
+/** The spec number and the optional `--repo` value, or null when either is missing. Pure. */
+export const parseArgs = (
+    argv: string[]
+): { number: number; repo: string | null } | null => {
+    const repoAt = argv.indexOf('--repo')
+    const repo = repoAt >= 0 ? argv[repoAt + 1] : null
+    if (repo === undefined) return null
+    const number = argv.find(
+        (arg, index) =>
+            /^\d+$/.test(arg) && (repoAt < 0 || index !== repoAt + 1)
+    )
+    return number === undefined ? null : { number: Number(number), repo }
+}
+
+const main = () => {
+    const args = parseArgs(Bun.argv.slice(2))
+    if (args === null) {
+        console.error(
+            'Usage: bun spec-bundle.ts <spec number> [--repo <owner/repo>]'
+        )
+        process.exit(1)
+    }
+    // `gh` fills in `{owner}/{repo}` from the repo of the current folder.
+    const repo = `repos/${args.repo ?? '{owner}/{repo}'}`
+    const issue = `${repo}/issues/${args.number}`
+    const raw = ghFound(issue)
+    const subs = ghFound(`${issue}/sub_issues?per_page=100`)
+    console.log(
+        formatSpecBundle({
+            spec: { ...toIssue(raw), labels: labelsOf(raw) },
+            tickets: listOf(subs).map(toIssue),
+            rule_files: ruleFiles(
+                fileText(ghApi(`${repo}/contents/.luca/config.json`))
+            ),
+            glossary: ghApi(`${repo}/contents/GLOSSARY.md`) !== null,
+            adr: ghApi(`${repo}/contents/docs/adr`) !== null,
+        })
+    )
+}
+
+if (import.meta.main) main()