@defrex/autobuild 0.8.0 → 0.9.0

package/skills/implement/SKILL.md

@@ -21,6 +21,9 @@ You never push — the push is plumbing that happens when you finish.
    operator's answer to the escalation that blocked this build). The manifest's
    `feedback` field names which one this round is, and is absent when the round
    carries none.
+   When the manifest lists `assets`, they are the build's pinned ticket assets
+   under `.ab/assets/<kind>/<name>/`; read them with the spec. A `design` asset
+   is a contract on observable visual and reference outcomes, not on implementation — what you build must satisfy it, while how stays yours.
 2. Execute the plan. Commit in coherent increments with real messages —
    the commit history is part of the paper trail.
 3. Run the repo's checks yourself before finishing (the config's typecheck /

package/skills/operate/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: operate
+description: You are the embedded orchestrator for one repository - the agent that answers its operator sessions, watches its builds, unblocks them, and discusses direction. You run inside the hosted service with the operator tool registry bound in process. Use this skill as your operating manual — it defines your role, the complete tool surface, the approval rules, and when to stop and ask the operator instead of acting.
+---
+
+# Operating the repository
+
+You are the orchestrator session for one repository. You file tickets, watch
+builds, unblock them, answer operator questions, and discuss direction. You
+are not a build phase: you never run pipeline steps, never edit the
+repository, and never touch a checkout. Your entire reach is the operator
+tool registry bound into your turn.
+
+## How you run
+
+Each of your turns is one durable agent loop:
+
+- The conversation is reconstructed from durable state on every invocation.
+  Nothing is held in memory between invocations; if your turn suspends and
+  resumes in a fresh invocation, the model input is identical.
+- Your output streams as protocol parts onto the turn's stream. The operator
+  sees it live in the session.
+- Every tool call is attributed to the session's operator — the human actor
+  named on every write is that operator, with your session as the delegate.
+  Act accordingly: you are spending their authority.
+- Your tools target exactly one repository, the session's own. You never
+  supply a repository argument; it is bound for you.
+
+## Suspension
+
+Your turn can stop in two ways, and both are normal:
+
+- **Budget.** Each invocation has a wall-clock budget. When it runs out, the
+  turn suspends (`cause: budget`) and resumes in a fresh invocation — a new
+  provider call — with the identical conversation. Never assume a turn
+  died; never repeat work a checkpoint already covers.
+- **Approval.** Some tools are on the repository's approval list. Calling
+  one suspends your turn (`cause: approval`) until the operator answers.
+  An `approve` answer executes the call; a `deny` answer hands you a denied
+  tool output — treat it as a firm no, say so briefly, and move on. Tools
+  not on the list run without pause.
+
+When suspended, just stop cleanly. Anything important you want to say should
+already be in your streamed output before the suspension point.
+
+## The tool surface
+
+Your tools are the operator registry. The read-only ones are always safe:
+
+- `builds.list` — active, queued, or all builds, with effective status.
+- `builds.get` — one build's detail.
+- `builds.events` — one build's event log from a cursor (use a cursor; logs
+  are long).
+- `builds.artifact` — one artifact's bytes, base64-encoded.
+- `repository.status` — the repository's derived status.
+- `harvest.status` — the observation workflow's current state.
+
+The mutating ones carry the operator's authority — prefer the narrowest
+that does the job, and say what you are doing before you do it:
+
+- `builds.control` — pause, resume, abort, or discard a build. `abort` and
+  `discard` are destructive to in-flight work.
+- `builds.answer` — answer an open escalation: guidance text, a retry, a
+  review-round ceiling, or a revise-spec resolution.
+- `tickets.list`, `tickets.get` — read the ticket queue and one ticket.
+- `tickets.create` — file a new ticket from a conversation.
+- `tickets.update`, `tickets.block`, `tickets.unblock` — edit fields and
+  blocker relations.
+- `tickets.move` — move a ticket between workflow states. Moving a ticket
+  into the ready state sends it to dispatch — do that only when the ticket
+  genuinely conforms and the operator's intent is clear.
+- `notes.read`, `notes.write` — the operator-notes artifact: durable,
+  human-readable notes about this repository's operation. Write what the
+  next turn (or the next human) will need; read it before acting on
+  anything you'd otherwise guess.
+- `repository.settings` and `repository.bulk_control` — repository-wide
+  switches; use sparingly and only on clear instruction.
+- `harvest.control` — start or control an observation run.
+
+Every tool returns the operator API's shapes: results, or a typed failure
+(`kind`, `error`, `code`). A refusal is information, not an exception:
+report it, adapt, and carry on.
+
+## The attention set
+
+When the session has wake settings, the dispatcher wakes you when a build
+event matching them lands. A wake turn's first message carries the event
+record and the build's reduced state as JSON. Typical wakes and what to do:
+
+- `escalation.raised` / `phase.failed` / `infrastructure.failed` — read the
+  escalation and the build's recent events; if the operator notes or the
+  conversation already answer it, say so; otherwise summarize and decide
+  whether it needs the operator.
+- `finalize.completed` / `build.completed` / `pr.merged` / `pr.closed` /
+  `pr.conflicted` / `build.aborted` — acknowledge outcome changes that the
+  operator should know about, and file or move tickets when the outcome
+  makes that obviously right.
+- Anything else matching the wake settings — read the event, then decide.
+
+Do not re-derive history the build's events already tell you; read events
+with a cursor and keep it short.
+
+## When to escalate instead of act
+
+Stop and ask the operator — in plain streamed text — whenever:
+
+- The action is destructive and not clearly instructed (`abort`, `discard`,
+  a bulk control, a repository-wide setting).
+- Two readings of the operator's intent diverge in cost or risk.
+- You would be guessing about product direction, priorities, or scope.
+- A tool refusal repeats and you cannot resolve it with the tools you have.
+- The attention event is one you cannot act on with the registry at all.
+
+Filing a ticket IS acting — do it when the request is concrete. Asking is
+not a failure; an unasked destructive action is.
+
+## Boundaries
+
+- You never claim to have done anything outside the registry. If you cannot
+  observe it with a tool, say you cannot observe it.
+- You never invent repository identity, ticket ids, or build slugs; every
+  id you act on came from a tool result or the conversation.
+- You do not run concurrent work: one turn at a time, and a message that
+  arrives mid-turn is answered after the current turn ends.
+- The operator's notes artifact is shared ground truth; keep it current
+  when you learn something durable.

package/skills/plan/SKILL.md

@@ -19,6 +19,10 @@ write product code in this phase.
    reviewer's findings) or `.ab/guidance.json` (a human operator's answer to
    the escalation that blocked this build). A round never carries both, and a
    round may carry neither.
+   When the manifest lists `assets`, they are the build's pinned ticket assets
+   under `.ab/assets/<kind>/<name>/`; read them with the spec. A `design` asset
+   is a contract on observable visual and reference outcomes, not on implementation — the plan must satisfy it, while how stays yours. The spec cites
+   assets by kind and name.
 2. Read the spec, then the codebase. The spec says what and why; you decide
    how. Explore enough of the code to name real files and real seams. When an
    approach touches a third-party service, ground it in the provider's own

package/skills/plan-review/SKILL.md

@@ -17,7 +17,11 @@ verdict travels the typed channel; nothing you print matters to the pipeline.
    lists finding ids a human explicitly dismissed.
 2. Judge the plan on exactly these axes:
    - **Spec conformance** — does executing this plan satisfy every
-     acceptance criterion? Does anything in it exceed the spec's scope?
+     acceptance criterion? Does anything in it exceed the spec's scope? A
+     pinned `design` asset (listed under `assets` in `.ab/context.json`, files
+     under `.ab/assets/<kind>/<name>/`) is a contract on observable visual and reference outcomes, not on implementation: open it and flag a plan that
+     contradicts or ignores it, as you would an unmet criterion. A gap in the
+     asset is not a reason to invent requirements.
    - **Groundedness** — do the files and seams it names actually exist and
      work the way the plan assumes? Spot-check the code; a plan built on a
      wrong assumption fails in `implement` at ten times the cost. For every

package/skills/spec/SKILL.md

@@ -37,7 +37,9 @@ in order, but as a conversation, not a form:
 3. **Out of scope.** Ask what adjacent work is explicitly excluded. Propose
    candidates — the tempting expansions you noticed while reading the code.
 4. **Evidence.** Link what exists: the error rates, the user reports, the
-   prior discussion.
+   prior discussion. Designs and other reference material are attached as
+   ticket assets and cited by kind and name — see
+   [Designs and reference material](#designs-and-reference-material).
 
 Draft the spec in full, show it, iterate until the user accepts. Then create
 the ticket with the spec as its body using `ab ticket create`. Honor a
@@ -102,6 +104,9 @@ spec to a file, then sync only the body:
 ab ticket update <ticket> --body spec.md
 ```
 
+If the human points at a design or other reference material while fleshing out,
+follow [Designs and reference material](#designs-and-reference-material).
+
 Omitted metadata is preserved, including title, labels, assignee, state, and
 provider-specific fields. If grooming changes dependencies, use the same
 configured-source surface rather than a provider API or MCP call:
@@ -114,10 +119,48 @@ ab ticket unblock <ticket> <blocker-id>
 The first id is the ticket being amended. Both relationship operations are
 idempotent; adding validates the blocker exists and rejects a self-block.
 
+## Designs and reference material
+
+When the user points at a design, mock, prototype, screenshot set, sample
+payload, or other reference material, export it during this conversation, so
+no build worker ever has to convert a link. Use whatever tools this session
+has (a browser, a connector, a screenshot tool, fetch, a CLI) and do not tie
+the result to any one design tool. Produce portable static files in one
+folder: a static reference page (`index.html`, with its assets inline or
+alongside) plus screenshots of the key states and widths.
+
+Attach the folder (or a single file) to the ticket as a `design` asset:
+
+```
+ab ticket attach <id> design <path> [--name <name>]
+```
+
+The ticket must exist first. For a new ticket, create it in a non-ready
+staging state, attach, and check with `ab ticket show <id>`. Then place it
+where the human asked: if the intended destination is ready, move it there
+last, so a build cannot claim it before its assets exist; otherwise leave it
+in its destination (or the configured create state) and do not promote it. Attaching the same
+kind and name again makes a new revision. Assets are frozen into a build when
+it claims the ticket; attaching afterward does not reach a build already
+running.
+
+Cite the asset in the spec's Evidence by kind and name (``design `home-page` ``),
+never by external link. The spec still states the underlying need; the asset is
+the visual contract.
+
+If this session cannot export the design (no tool for it, an auth wall, or
+files over the store's size limit), keep the external link in Evidence and say
+plainly, in the spec and to the human, that builds cannot read it, so the
+planner does not treat it as a contract.
+
 ## Rules
 
-- The spec says **what and why, never how** — if the user hands you a
-  design, capture the underlying need and park the design in evidence as
+- The spec says **what and why, never how.** An exported, attached `design`
+  asset is a contract on observable visual and reference outcomes — layout,
+  content, states, copy, look — that plan, review, and verify judge against;
+  it is not a contract on implementation, and component structure, libraries,
+  and file layout stay the planner's. A technical design or proposed approach
+  the user hands you, and any link you could not export, goes in Evidence as
   "proposed approach", clearly non-binding on the planner.
 - Don't gold-plate: a spec is buildable when a planner could start, not when
   every question is answered. Thin-but-groomed is a valid state — dispatch

package/packages/core/src/cli/dashboard/frame-image.ts

@@ -1,373 +0,0 @@
-import { readdirSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { dirname, join } from 'node:path'
-import { Resvg } from '@resvg/resvg-js'
-import { distributionPath } from '../../distribution'
-import { graphemes } from './cells'
-
-/**
- * Deterministic dashboard-frame rendering.
- *
- * The dashboard deliberately emits a tiny terminal vocabulary: SGR reset,
- * bold/dim and six named foreground colours, plus OSC 8 hyperlinks. This
- * adapter accepts exactly that vocabulary. Unknown control traffic is an
- * error rather than evidence that merely looks plausible after bytes were
- * dropped.
- */
-
-const ESC = '\x1b'
-const BEL = '\x07'
-const FONT_FAMILY = 'DejaVu Sans Mono'
-const FONT_FAMILIES = [
-  FONT_FAMILY,
-  'Dashboard CJK 113',
-  'Dashboard CJK 117',
-  'Dashboard CJK 118',
-  'Dashboard Emoji Flags',
-  'Dashboard Emoji Food',
-  'Dashboard Emoji People',
-].join(', ')
-const FONT_SIZE = 16
-const CELL_WIDTH = 10
-const LINE_HEIGHT = 20
-const PADDING_X = 12
-const PADDING_Y = 10
-const BASELINE = 16
-const EMOJI_CLUSTER = /\p{Extended_Pictographic}|\p{Regional_Indicator}/u
-
-const PALETTE = {
-  background: '#0d1117',
-  foreground: '#c9d1d9',
-  red: '#ff7b72',
-  green: '#3fb950',
-  yellow: '#d29922',
-  blue: '#58a6ff',
-  cyan: '#39c5cf',
-} as const
-
-type Foreground = Exclude<keyof typeof PALETTE, 'background'>
-
-interface Style {
-  foreground: Foreground
-  bold: boolean
-  dim: boolean
-  href?: string
-}
-
-interface TextRun {
-  column: number
-  cells: number
-  text: string
-  style: Style
-}
-
-interface ParsedLine {
-  text: string
-  cells: number
-  runs: TextRun[]
-}
-
-export interface FrameImageOptions {
-  /** Declared terminal width. Every parsed line must fit this grid. */
-  columns: number
-}
-
-export interface RenderedFrameImage {
-  /** ANSI/OSC-free text from the exact parsed cells, with a final newline. */
-  text: string
-  svg: string
-  png: Uint8Array
-  width: number
-  height: number
-  rows: number
-  columns: number
-}
-
-function cloneStyle(style: Style): Style {
-  return {
-    foreground: style.foreground,
-    bold: style.bold,
-    dim: style.dim,
-    ...(style.href !== undefined ? { href: style.href } : {}),
-  }
-}
-
-function sameStyle(left: Style, right: Style): boolean {
-  return (
-    left.foreground === right.foreground &&
-    left.bold === right.bold &&
-    left.dim === right.dim &&
-    left.href === right.href
-  )
-}
-
-function applySgr(style: Style, raw: string, line: number): void {
-  const codes = raw === '' ? [0] : raw.split(';').map((part) => Number(part))
-  if (codes.some((code) => !Number.isInteger(code))) {
-    throw new Error(`dashboard frame line ${line}: malformed SGR sequence ESC[${raw}m`)
-  }
-  for (const code of codes) {
-    switch (code) {
-      case 0:
-        style.foreground = 'foreground'
-        style.bold = false
-        style.dim = false
-        break
-      case 1:
-        style.bold = true
-        break
-      case 2:
-        style.dim = true
-        break
-      case 22:
-        style.bold = false
-        style.dim = false
-        break
-      case 31:
-        style.foreground = 'red'
-        break
-      case 32:
-        style.foreground = 'green'
-        break
-      case 33:
-        style.foreground = 'yellow'
-        break
-      case 34:
-        style.foreground = 'blue'
-        break
-      case 36:
-        style.foreground = 'cyan'
-        break
-      case 39:
-        style.foreground = 'foreground'
-        break
-      default:
-        throw new Error(`dashboard frame line ${line}: unsupported SGR code ${code} in ESC[${raw}m`)
-    }
-  }
-}
-
-function parseLine(value: string, lineNumber: number): ParsedLine {
-  const style: Style = {
-    foreground: 'foreground',
-    bold: false,
-    dim: false,
-  }
-  const runs: TextRun[] = []
-  let text = ''
-  let cells = 0
-
-  const append = (cluster: string, width: number): void => {
-    const previous = runs.at(-1)
-    // ASCII runs may coalesce. Unicode clusters stay independently pinned to
-    // their terminal cell columns so font fallback/advance cannot shift the
-    // run that follows a wide glyph.
-    if (
-      previous !== undefined &&
-      previous.column + previous.cells === cells &&
-      /^[\x20-\x7e]*$/.test(previous.text) &&
-      /^[\x20-\x7e]$/.test(cluster) &&
-      sameStyle(previous.style, style)
-    ) {
-      previous.text += cluster
-      previous.cells += width
-    } else {
-      runs.push({ column: cells, cells: width, text: cluster, style: cloneStyle(style) })
-    }
-    text += cluster
-    cells += width
-  }
-
-  for (let index = 0; index < value.length; ) {
-    if (value[index] === ESC) {
-      const family = value[index + 1]
-      if (family === '[') {
-        const rest = value.slice(index + 2)
-        const match = /^([0-9;]*)m/.exec(rest)
-        if (match === null) {
-          throw new Error(
-            `dashboard frame line ${lineNumber}: unsupported or unterminated CSI sequence`,
-          )
-        }
-        applySgr(style, match[1]!, lineNumber)
-        index += 2 + match[0].length
-        continue
-      }
-      if (family === ']') {
-        const end = value.indexOf(BEL, index + 2)
-        if (end === -1) {
-          throw new Error(`dashboard frame line ${lineNumber}: unterminated OSC sequence`)
-        }
-        const payload = value.slice(index + 2, end)
-        const match = /^8;;(.*)$/.exec(payload)
-        if (match === null) {
-          throw new Error(
-            `dashboard frame line ${lineNumber}: unsupported OSC sequence ${JSON.stringify(payload)}`,
-          )
-        }
-        const href = match[1]!
-        style.href = href === '' ? undefined : href
-        index = end + 1
-        continue
-      }
-      throw new Error(
-        `dashboard frame line ${lineNumber}: unsupported escape family ${JSON.stringify(family ?? '')}`,
-      )
-    }
-
-    const nextEscape = value.indexOf(ESC, index)
-    const stop = nextEscape === -1 ? value.length : nextEscape
-    const plain = value.slice(index, stop)
-    for (const character of plain) {
-      const code = character.codePointAt(0)!
-      if (code < 0x20 || code === 0x7f || (code >= 0x80 && code <= 0x9f)) {
-        throw new Error(
-          `dashboard frame line ${lineNumber}: unsupported control U+${code
-            .toString(16)
-            .toUpperCase()
-            .padStart(4, '0')}`,
-        )
-      }
-    }
-    for (const cluster of graphemes(plain)) append(cluster.text, cluster.width)
-    index = stop
-  }
-
-  if (style.href !== undefined) {
-    throw new Error(`dashboard frame line ${lineNumber}: OSC 8 hyperlink was not closed`)
-  }
-  if (style.foreground !== 'foreground' || style.bold || style.dim) {
-    throw new Error(
-      `dashboard frame line ${lineNumber}: SGR style was not reset before end of line`,
-    )
-  }
-  return { text, cells, runs }
-}
-
-function xml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&apos;')
-}
-
-function svgFor(
-  parsed: ParsedLine[],
-  columns: number,
-): {
-  svg: string
-  width: number
-  height: number
-} {
-  const width = PADDING_X * 2 + columns * CELL_WIDTH
-  const height = PADDING_Y * 2 + Math.max(1, parsed.length) * LINE_HEIGHT
-  const content: string[] = []
-
-  for (const [row, line] of parsed.entries()) {
-    for (const run of line.runs) {
-      const x = PADDING_X + run.column * CELL_WIDTH
-      const y = PADDING_Y + BASELINE + row * LINE_HEIGHT
-      const opacity = run.style.dim ? ' fill-opacity="0.58"' : ''
-      const weight = run.style.bold ? ' font-weight="700"' : ' font-weight="400"'
-      // DejaVu's native advance is slightly narrower than the 10 px evidence
-      // grid. Fit coalesced ASCII runs to their exact terminal cells so the
-      // error cannot accumulate into a visible gap before a pinned Unicode
-      // cluster. Emoji get the same exact fit at a slightly larger size: the
-      // monochrome fallback remains readable without crossing its cell range.
-      const emoji = EMOJI_CLUSTER.test(run.text)
-      const geometry =
-        /^[\x20-\x7e]+$/.test(run.text) || emoji
-          ? ` textLength="${run.cells * CELL_WIDTH}" lengthAdjust="spacingAndGlyphs"`
-          : ''
-      const size = emoji ? ' font-size="18"' : ''
-      const node =
-        `<text x="${x}" y="${y}" fill="${PALETTE[run.style.foreground]}"` +
-        `${weight}${opacity}${geometry}${size}>${xml(run.text)}</text>`
-      content.push(
-        run.style.href === undefined ? node : `<a href="${xml(run.style.href)}">${node}</a>`,
-      )
-    }
-  }
-
-  return {
-    width,
-    height,
-    svg: [
-      `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">`,
-      `<rect width="${width}" height="${height}" fill="${PALETTE.background}"/>`,
-      `<g font-family="${FONT_FAMILIES}" font-size="${FONT_SIZE}" xml:space="preserve" text-rendering="geometricPrecision">`,
-      ...content,
-      '</g>',
-      '</svg>',
-    ].join(''),
-  }
-}
-
-function fontFiles(): string[] {
-  const require = createRequire(import.meta.url)
-  const root = dirname(require.resolve('dejavu-fonts-ttf/package.json'))
-  const fallbacks = distributionPath('tools', 'fonts')
-  return [
-    join(root, 'ttf', 'DejaVuSansMono.ttf'),
-    join(root, 'ttf', 'DejaVuSansMono-Bold.ttf'),
-    ...readdirSync(fallbacks)
-      .filter((name) => name.endsWith('.ttf'))
-      .sort()
-      .map((name) => join(fallbacks, name)),
-  ]
-}
-
-/** Parse once, then derive both evidence forms from the same exact cells. */
-export function renderDashboardFrameImage(
-  lines: readonly string[],
-  options: FrameImageOptions,
-): RenderedFrameImage {
-  if (!Number.isInteger(options.columns) || options.columns <= 0) {
-    throw new Error(`dashboard frame columns must be a positive integer, got ${options.columns}`)
-  }
-  if (lines.length === 0) {
-    throw new Error('dashboard frame is empty')
-  }
-  const parsed = lines.map((line, index) => parseLine(line, index + 1))
-  for (const [index, line] of parsed.entries()) {
-    if (line.cells > options.columns) {
-      throw new Error(
-        `dashboard frame line ${index + 1} is ${line.cells} cells wide, exceeding declared terminal width ${options.columns}`,
-      )
-    }
-  }
-
-  const { svg, width, height } = svgFor(parsed, options.columns)
-  const rendered = new Resvg(svg, {
-    fitTo: { mode: 'original' },
-    background: PALETTE.background,
-    font: {
-      fontFiles: fontFiles(),
-      loadSystemFonts: false,
-      defaultFontFamily: FONT_FAMILY,
-      monospaceFamily: FONT_FAMILY,
-      defaultFontSize: FONT_SIZE,
-    },
-    shapeRendering: 2,
-    textRendering: 2,
-    imageRendering: 0,
-    logLevel: 'off',
-  }).render()
-  if (rendered.width !== width || rendered.height !== height) {
-    throw new Error(
-      `dashboard PNG dimensions ${rendered.width}x${rendered.height} did not match SVG ${width}x${height}`,
-    )
-  }
-
-  return {
-    text: `${parsed.map((line) => line.text).join('\n')}\n`,
-    svg,
-    png: new Uint8Array(rendered.asPng()),
-    width,
-    height,
-    rows: lines.length,
-    columns: options.columns,
-  }
-}