@defrex/autobuild 0.9.0 → 0.10.0

package/packages/core/src/store/snapshots.ts

@@ -0,0 +1,88 @@
+/**
+ * Reducer snapshots: a cache beside the event log, never an authority.
+ *
+ * For one scope (a build log or a repository journal) and one registered
+ * reducer, the store may keep that reducer's serialized accumulator as of a
+ * cursor, so a process with no hot memory loads it, reads only the events
+ * newer than the cursor, and advances — instead of replaying the whole log.
+ *
+ * The log always regenerates a snapshot. Every consumer treats a missing,
+ * version-mismatched, ahead-of-log, malformed or unreadable snapshot as a miss
+ * and replays; deleting every snapshot changes no observable output.
+ */
+import { z } from 'zod'
+import type { IncrementalReducer } from '../kernel/incremental'
+import type { BuildStore } from './types'
+
+export type SnapshotScope = { kind: 'build'; slug: string } | { kind: 'repo'; repo: string }
+
+export interface ReducerSnapshot {
+  /** The reducer version that wrote `state`; a reader on another version
+   * ignores the snapshot. */
+  version: number
+  /** The greatest event seq folded into `state`. */
+  cursor: number
+  /** The reducer's JSON accumulator as of `cursor`. */
+  state: unknown
+}
+
+export const reducerSnapshotWireSchema = z.object({
+  version: z.number().int().min(1),
+  cursor: z.number().int().min(0),
+  state: z.unknown(),
+})
+
+/** The registry name a snapshot is keyed by: a short identifier, safe in a URL
+ * path segment and a SQL key. */
+export const SNAPSHOT_REDUCER_NAME = /^[A-Za-z][A-Za-z0-9._-]{0,63}$/
+
+export function snapshotScopeKey(scope: SnapshotScope): string {
+  return scope.kind === 'build' ? `build:${scope.slug}` : `repo:${scope.repo}`
+}
+
+/** Whether a put replaces the stored row. The stored cursor never decreases:
+ * a higher cursor wins whatever the versions, and an upgraded reducer replaces
+ * an older shape at an unchanged cursor. */
+export function snapshotSupersedes(
+  next: Pick<ReducerSnapshot, 'version' | 'cursor'>,
+  stored: Pick<ReducerSnapshot, 'version' | 'cursor'> | undefined,
+): boolean {
+  if (stored === undefined) return true
+  if (next.cursor !== stored.cursor) return next.cursor > stored.cursor
+  return next.version > stored.version
+}
+
+type SnapshotStore = Pick<BuildStore, 'getReducerSnapshot' | 'putReducerSnapshot'>
+
+/** Read a snapshot, degrading every failure to a miss. */
+export async function loadReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  reducer: Pick<IncrementalReducer<unknown, unknown, unknown>, 'version'>,
+): Promise<ReducerSnapshot | null> {
+  if (store.getReducerSnapshot === undefined) return null
+  try {
+    const found = await store.getReducerSnapshot(scope, name, reducer.version)
+    if (found === null || found.version !== reducer.version) return null
+    if (!Number.isInteger(found.cursor) || found.cursor < 0) return null
+    return found
+  } catch {
+    return null
+  }
+}
+
+/** Write a snapshot best-effort; a failing store never reaches the caller. */
+export async function persistReducerSnapshot(
+  store: Partial<SnapshotStore>,
+  scope: SnapshotScope,
+  name: string,
+  snapshot: ReducerSnapshot,
+): Promise<boolean> {
+  if (store.putReducerSnapshot === undefined) return false
+  try {
+    return await store.putReducerSnapshot(scope, name, snapshot)
+  } catch {
+    return false
+  }
+}

package/packages/core/src/store/ticket-assets.ts

@@ -10,6 +10,7 @@
 
 import type { AbEvent } from '../events/catalog'
 import type { PinnedAsset } from '../events/payloads'
+import { defineReducer } from '../kernel/incremental'
 import { contentHash, type BlobStore, type BuildStore } from './types'
 
 export type { PinnedAsset }
@@ -379,19 +380,40 @@ export async function samplePinnedAssets(
   return (await store.listTicketAssets(repo, ticketId)).map(pinnedAssetOf)
 }
 
-/** Latest-pinned revision of `kind/name` as the build's events record it, or
- * (with `rev`) the revision when any pin in the log named it. */
-export function findPinnedRevision(
-  events: AbEvent[],
+export const PINNED_ASSETS_REDUCER_VERSION = 1
+
+/** The asset sets recorded by every `build.created`/`spec.revised` pin event
+ * that carries one, in array order. Each pin event replaces the set, so the
+ * newest decides the live pin; all of them answer "was this revision ever
+ * named". `pinnedRevision` is the query over the finished state. */
+export const pinnedAssetsReducer = defineReducer<
+  { pins: PinnedAsset[][] },
+  AbEvent,
+  { pins: PinnedAsset[][] }
+>({
+  version: PINNED_ASSETS_REDUCER_VERSION,
+  initial: () => ({ pins: [] }),
+  fold(acc, events) {
+    for (const event of events) {
+      if (event.type !== 'build.created' && event.type !== 'spec.revised') continue
+      const assets = event.payload.assets
+      if (assets === undefined) continue
+      acc.pins.push(assets)
+    }
+  },
+  finish: (acc) => ({ pins: acc.pins.slice() }),
+})
+
+/** Latest-pinned revision of `kind/name` over a reduced pin state, or (with
+ * `rev`) the revision when any pin named it. */
+export function pinnedRevision(
+  state: { pins: readonly (readonly PinnedAsset[])[] },
   kind: string,
   name: string,
   rev?: number,
 ): number | undefined {
   let latest: number | undefined
-  for (const event of events) {
-    if (event.type !== 'build.created' && event.type !== 'spec.revised') continue
-    const assets = event.payload.assets
-    if (assets === undefined) continue
+  for (const assets of state.pins) {
     if (rev !== undefined) {
       if (assets.some((a) => a.kind === kind && a.name === name && a.revision === rev)) return rev
       continue
@@ -403,6 +425,17 @@ export function findPinnedRevision(
   return latest
 }
 
+/** Latest-pinned revision of `kind/name` as the build's events record it, or
+ * (with `rev`) the revision when any pin in the log named it. */
+export function findPinnedRevision(
+  events: AbEvent[],
+  kind: string,
+  name: string,
+  rev?: number,
+): number | undefined {
+  return pinnedRevision(pinnedAssetsReducer.reduce(events), kind, name, rev)
+}
+
 /** `BuildStore.getPinnedTicketAsset` for any adapter: read the build's own
  * events to find the pinned revision, then fetch exactly that revision from the
  * ticket's assets. Earlier revisions stay retrievable after a replace or a

package/packages/core/src/store/types.ts

@@ -26,6 +26,8 @@ import type {
 } from '../events/sessions'
 export type { SessionEventEnvelope }
 import type { TicketRef } from '../ontology'
+import type { ReducerSnapshot, SnapshotScope } from './snapshots'
+export type { ReducerSnapshot, SnapshotScope }
 import type {
   TicketAsset,
   TicketAssetInput,
@@ -115,6 +117,12 @@ export interface BuildDigest {
    * when any of its merges is strictly after the oldest unclaimed
    * observation). */
   merged?: string
+  /** A `pr-attachment.hosted` has no later matching `pr-attachment.reclaimed`
+   * (the `pendingPrAttachmentReclaims` rule). Absent otherwise. */
+  reclaimPending?: true
+  /** The latest `execution.started` has no later `execution.ended` with the
+   * same `instance` (the `openExecution` rule). Absent otherwise. */
+  executionOpen?: true
 }
 
 export interface RepositoryRecord {
@@ -365,6 +373,36 @@ export interface BuildStore {
    * replay yields (`projectRepositoryStateEvents` is the normative oracle).
    * Unknown repo rejects like `getRepoEvents`. */
   getRepoStateEvents(repo: string): Promise<RepositoryEvent[]>
+  /** The journal's true high-water mark: the greatest assigned seq of any
+   * event type, 0 for an empty journal. Returns no event rows — the cursor a
+   * long-lived reader (the dispatcher's repository view) needs to resume with
+   * `getRepoEvents(repo, cursor)` even when the bounded subset excludes the
+   * journal's trailing events. Unknown repo rejects like `getRepoEvents`;
+   * never an `ensureRepo` side effect. */
+  getRepoHighWater(repo: string): Promise<number>
+  /** The stored reducer snapshot for a scope (a build log or a repository
+   * journal), a cache beside the log and never an authority. `null` when
+   * absent, when the stored version differs from `version`, when the stored
+   * cursor is ahead of the scope's log tail, or when the scope is unknown (no
+   * `ensureRepo` side effect, no rejection). A store without snapshot storage
+   * answers `null`. */
+  getReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    version: number,
+  ): Promise<ReducerSnapshot | null>
+  /** Upsert a reducer snapshot; the stored cursor never decreases. Writes only
+   * when no row exists, when `cursor` is above the stored one (whatever the
+   * versions — a mismatched row is replaced as soon as any writer advances
+   * past it), or when the cursor is equal and `version` is higher. Everything
+   * else, and any cursor beyond the log tail, is a no-op. Atomic, so
+   * concurrent writers cannot undo each other's progress. Resolves `true`
+   * when the row was written. */
+  putReducerSnapshot(
+    scope: SnapshotScope,
+    reducer: string,
+    snapshot: ReducerSnapshot,
+  ): Promise<boolean>
   putRepoArtifact(repo: string, artifact: ArtifactInput): Promise<RepositoryArtifactMeta>
   getRepoArtifact(repo: string, kind: string, rev?: number): Promise<RepositoryArtifact | null>
   listRepoArtifacts(repo: string, kind?: string): Promise<RepositoryArtifactMeta[]>

package/skills/guide/SKILL.md

@@ -732,7 +732,8 @@ state eligible.
 |---|---|---|---|
 | `source` | — | **required**, nonblank builtin or plugin registration name | Which provider backs all ticket operations. Unknown names report every available builtin and plugin source. |
 | `readyLabels` | — (source-aware) | optional; array of nonempty strings | A ticket must carry **every** listed label to be dispatchable. `[]` = **no label gate**. Absent uses the source default below. |
-| `readyState` | — | **required**, non-blank string | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file canonicalizes it to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `readyState` | — | **required**, non-blank string | The one workflow state a ticket must sit in to be dispatchable. Linear matches exactly and case-sensitively; file matches it case-insensitively to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `readyAssignee` | — | optional; `"me"` or an email; `linear` only | Also require the ticket to be assigned to that Linear user (`me` = owner of `LINEAR_API_KEY`); unassigned tickets are never ready. |
 | `teamKey` | — | required by `linear`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`) or an existing plugin configuration field. |
 | `claimedState` | — | optional nonempty string; forbidden by `file`, allowed for plugins | Workflow state `claim()` moves a ticket to when a build starts. |
 | `createState` | — | optional, nonempty string | Default state for new tickets when a create does not name one. Absent = the provider's default (Linear: the team's default, e.g. Backlog; file: Triage). |
@@ -772,11 +773,16 @@ Cross-field rules, each an **error**:
   janitor completion. Every source-agnostic `ab ticket` command loads and uses
   the same configured registration.
 
-The file tracker is **directory-per-state**: `<dir>/<state>/<id>.md` over
-`triage/ ready/ doing/ done/`. The directory *is* the state, so a transition or
+The file tracker is **directory-per-state**: `<dir>/<state>/<id>.md`, where
+every directory directly under the root is a state: the four lifecycle
+directories `triage/ ready/ doing/ done/` (always present, created on first use)
+plus any others the repository adds, such as `icebox/`. A state exists when its
+directory exists; state names match directories case-insensitively, and a name
+with no directory is an error listing those that exist. The directory *is* the
+state, so a transition or
 claim is a rename — frontmatter carries no `state`/`claimedBy`, and a ticket
 body survives byte-exactly because a move never rewrites the file. A malformed
-record in any lifecycle directory is diagnosed with its path and validation
+record in any state directory is diagnosed with its path and validation
 problem, left untouched, and excluded from listing/claim so unrelated valid
 ready work can continue. `ab ticket list` sends those diagnostics to stderr and
 keeps JSON stdout as one bare valid-ticket array. Tracker-wide safety checks
@@ -784,8 +790,8 @@ remain fatal: the same id in two state dirs is a loud error naming both paths,
 as are root-level ticket files with no state and filesystem failures. When
 `dir` is defaulted, the backlog writes its own `.gitignore` of `*`, so git never sees it; an
 explicit `dir` is the user's and is left alone. Agents and operators drive it
-through the source-agnostic `ab ticket` commands rather than running `mv` by
-hand.
+through the source-agnostic `ab ticket` commands rather than running `mv` or
+`mkdir` by hand; `ab ticket state create` makes a new state.
 
 **Secrets never live in this file.** `LINEAR_API_KEY` and plugin-declared
 `requiredEnv` credentials are environment variables (a local `.env` works).
@@ -1063,6 +1069,19 @@ with Linear and the file tracker, without provider-specific API/MCP calls:
   labeled metadata and the body verbatim, so it can read a stored spec back.
 - `ab ticket move <id> <state> [--json]` transitions one ticket and reports its
   post-transition value.
+- `ab ticket states [--json]` lists every state of the configured source:
+  lifecycle states first (triage, ready, doing, done), then custom states
+  alphabetically. Each row has the state name, the roles it plays under the
+  current config (create, ready, claimed, triage, proposal, done, or none), its
+  ticket count, and its purpose when set. `--json` emits one bare array of
+  `{name, roles, tickets, about?}`.
+- `ab ticket state create <name> [--about <text>] [--json]` makes a state, for
+  example `icebox`. It is idempotent: an existing state is reported as already
+  existing, and `--about` (one line) records or replaces its purpose. A name is
+  one to forty lowercase letters, digits, and hyphens starting with a letter,
+  and may not match an existing state case-insensitively. There is no rename or
+  delete. Only the file source supports `states` and `state create`; other
+  sources exit nonzero naming the source and the unsupported operation.
 
 State names and ids are source-local. For block and unblock, the first id is the
 ticket being changed and the comma-separated second operand names its blockers.
@@ -1849,7 +1868,7 @@ default, when you need to know what this repo's version says).
 | Skill | Place in the lifecycle | Purpose |
 |---|---|---|
 | `ab-spec` | Before a build exists | Design a feature spec-first through conversation, or flesh out a ticket to the spec standard. The human-interactive surface; takes a ticket, not a build slug. **Model-invocable.** |
-| `ab-tickets` | Before a build exists | Drive this repo's local file tracker: create a ticket, report the backlog, groom or move one between `triage/ ready/ doing/ done/`. The agent-facing surface on the tracker — use it instead of `mv`. **Model-invocable.** |
+| `ab-tickets` | Before a build exists | Drive this repo's local file tracker: create a ticket, report the backlog, groom or move one between the lifecycle directories (`triage/ ready/ doing/ done/`) and any repository-defined states, including the icebox. The agent-facing surface on the tracker — use it instead of `mv`. **Model-invocable.** |
 | `ab-guide` | Outside the pipeline | This skill: reference for the lifecycle, config surface, setup/upgrade behavior, and the installed skills. Its editable `references/setup.md` guides the init handoff. **Model-invocable.** |
 | `ab-harvest` | harvest `synthesize` step | Continue the producer across review rounds: cluster the claimed structured observations and author typed spec-standard create/join/suppress proposals. Runner-only. |
 | `ab-harvest-review` | harvest `review` step | Fresh adversarial reviewer for proposal coverage, semantic dedup, spec quality, and evidence; returns `approve`/`revise`/`escalate`. Runner-only. |

package/skills/guide/references/remote-store-protocol.md

@@ -297,6 +297,8 @@ it to exist. An unknown build returns `404 not-found`.
 | `appendIfCurrent` | `POST /builds/{slug}/events/conditional` | `{"expectedSeq": nonnegative integer, "event": event write}` | appended: `201` + build event envelope; stream advanced: `200 null` |
 | `getEvents` | `GET /builds/{slug}/events?since={n}&wait={s}` | optional `since` query value, parsed below; absence defaults to `0`. Optional `wait` in whole seconds, parsed per the event-wait rules below | `200` + envelopes whose `seq` is strictly greater than parsed `since`, in increasing sequence order |
 | `appendWithArtifacts` | `POST /builds/{slug}/deposits` | atomic deposit request | `201` + `{event, artifacts}` |
+| `getReducerSnapshot` | `GET /builds/{slug}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, or ahead of the build log's tail; an unknown build is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` | `PUT /builds/{slug}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the log's tail answer `written: false` |
 | `putArtifact` | `POST /builds/{slug}/artifacts` | artifact input | `201` + build artifact metadata |
 | `getArtifact` | `GET /builds/{slug}/artifacts?kind={kind}&rev={n}` | `kind` is required and nonempty; optional `rev` is parsed below | `200` + artifact read; an absent `rev` parameter selects the latest revision; a missing kind/revision is `200 null` |
 | `listArtifacts` | `GET /builds/{slug}/artifact-list?kind={kind}` | optional `kind`; absence means all kinds | `200` + metadata ordered by kind and then increasing revision |
@@ -336,6 +338,32 @@ part of this protocol. Retention is enforced server-side inside the store at
 deposit time (bounded pruning of dispatcher run/config artifact revisions),
 not through any endpoint.
 
+### Reducer snapshots
+
+A reducer snapshot is one registered reducer's serialized state as of a log
+cursor, kept per scope (one build log or one repository journal) and reducer
+name. It is a cache the log regenerates, never an authority: a process with no
+hot memory loads it, reads only the events newer than its cursor, advances the
+reducer, and writes the advanced state back, and deleting every snapshot changes
+no observable output. The routes above and in section 4 are additive and carry
+no protocol-version bump. The store, not the client, enforces the invariants:
+
+- the stored cursor never decreases, whatever the versions of the competing
+  writers; a write succeeds only when no row exists, when its cursor is above the
+  stored one, or when its cursor equals the stored one and its version is higher
+  (an upgraded reducer replacing the old shape at an unchanged tail);
+- a read answers `null` for a row whose version differs from the requested one,
+  and for one whose cursor is beyond the scope's log tail; a write beyond the
+  tail is refused;
+- an unknown build or repository answers `null` (read) or `written: false`
+  (write) and never creates the scope.
+
+A client treats `404` and `405` from either route as "no snapshot", so a client
+newer than its store replays the log with no error, and a client older than its
+store never calls the routes. Authentication and transport failures still
+surface normally. A build token may touch only its own build's snapshots and a
+repository token only its own repository's, exactly as for events.
+
 ### The event-read bounded wait
 
 Both event reads (`getEvents` and, symmetrically, the `getRepoEvents` read of
@@ -382,6 +410,8 @@ without a journal record, or a repository without builds.
 | `appendRepo` | `POST /repos/{repo}/events` | event write | `201` + repository event envelope |
 | `getRepoEvents` | `GET /repos/{repo}/events?since={n}&wait={s}` | optional `since` query value, parsed as in section 3; absence defaults to `0`. Optional `wait` in whole seconds, per the event-wait rules of section 3 | `200` + envelopes with `seq >` parsed `since`, in increasing sequence order |
 | `getRepoStateEvents` | `GET /repos/{repo}/state-events` | none | `200` + the bounded repository-journal subset (AUT-489): every durable event type (`harvest.*`, `orchestrator.sandbox.*`, the three dispatcher setting types) plus, when the journal has one, the tail from the latest `dispatcher.run-started`, in increasing sequence order; served inside the repository-existence gate like `GET events`, so an unknown repository is `404` |
+| `getReducerSnapshot` (repo scope) | `GET /repos/{repo}/snapshots/{reducer}?version={n}` | required `version` query value, a positive integer; `reducer` is a registry name (`^[A-Za-z][A-Za-z0-9._-]{0,63}$`) | `200` + `{"version", "cursor", "state"}` or `200 null` when absent, written by another reducer version, ahead of the journal's tail, or the repository has no journal record; an unknown repository is `404`, which the shipped client also maps to `null` |
+| `putReducerSnapshot` (repo scope) | `PUT /repos/{repo}/snapshots/{reducer}` | `{"version": int >= 1, "cursor": int >= 0, "state": JSON}`, at most 16 MiB (`413` above) | `200 {"written": boolean}`; the stored cursor never decreases, so a write at an equal or lower cursor (or an equal cursor at an equal or lower version) and one past the journal's tail answer `written: false` |
 | `appendRepoWithArtifacts` | `POST /repos/{repo}/deposits` | atomic deposit request | `201` + `{event, artifacts}` using repository shapes |
 | `putRepoArtifact` | `POST /repos/{repo}/artifacts` | artifact input | `201` + repository artifact metadata |
 | `getRepoArtifact` | `GET /repos/{repo}/artifacts?kind={kind}&rev={n}` | required nonempty `kind`; optional `rev` is parsed as in section 3 | `200` + artifact read; latest only when the `rev` parameter is absent; missing kind/revision is `200 null` |
@@ -834,6 +864,11 @@ resource access; an explicit resource whose id is `"*"` is not admin.
 | repo | no | no | no | exact id only | yes | exact id only | exact id only | exact repo only | no |
 | session | no | no | no | no | no | no | no | no | exact id only |
 
+The snapshot routes (`/builds/{slug}/snapshots/{reducer}` and
+`/repos/{repo}/snapshots/{reducer}`) follow the one-matching-build and
+one-matching-repo columns: a build token reads and writes only its own build's
+snapshots, a repo token only its own repository's.
+
 A valid token used for the wrong resource receives `403 auth`. Resource scope
 gates all operations, including reads, artifact operations, and leases. A
 session resource token's authority is exactly its one session — it cannot

package/skills/tickets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tickets
-description: Work this repo's local ticket tracker — create or edit a ticket, amend blockedBy dependencies, report the backlog, move work between triage/ready/doing/done, or answer "what's the status of ticket X". Use whenever the user asks about tickets, blockers, the backlog, or wants something queued for autobuild to build.
+description: Work this repo's local ticket tracker — create or edit a ticket, amend blockedBy dependencies, report the backlog, triage the inbox, move work between the lifecycle directories and any repository-defined states such as the icebox, or answer "what's the status of ticket X". Use whenever the user asks about tickets, blockers, the backlog, or wants something queued for autobuild to build.
 ---
 
 # /tickets
@@ -12,7 +12,11 @@ content and blocker relationships. The default file source needs no secret.
 ## Where it lives
 
 `.autobuild/tickets/` by default (if `autobuild.toml` has a `[tickets] dir`,
-that directory instead), holding exactly four state directories:
+that directory instead), holding the four lifecycle state directories plus any others this repo adds.
+`triage/`, `ready/`, `doing/`, and `done/` are the lifecycle directories the
+dispatcher uses. Any other directory is a repository-defined state: the
+dispatcher never moves tickets into it and never dispatches from it unless
+`autobuild.toml` names it (for example `readyState` or `proposalState`).
 
 ```
 .autobuild/tickets/
@@ -20,6 +24,7 @@ that directory instead), holding exactly four state directories:
   ready/    # groomed; file lifecycle-state gate satisfied
   doing/    # claimed; a build is running
   done/     # merged
+  icebox/   # example of a repo-added state, present only once created
 ```
 
 **A ticket's state is the directory it is in.** There is no `state` field
@@ -71,13 +76,17 @@ retry, and adding validates the blocker exists and is not the ticket itself.
 ## Report the backlog
 
 ```
+ab ticket states                # every state, lifecycle and custom: role, count, purpose
 ls .autobuild/tickets/ready     # groomed candidates in the ready lifecycle state
 ls .autobuild/tickets/doing     # what's building right now
 ```
 
 The filename is the id. For a title, read the file's frontmatter. To report
-the whole backlog, list all four directories — that listing is complete and
-current by construction.
+the whole backlog, cover every state — lifecycle and custom — via
+`ab ticket states` or by listing every directory under the tracker root, so the
+report includes `icebox/` and any other category. `ab ticket list` without
+filters shows only the ready state, regardless of custom states, so it is not a
+backlog report.
 
 ## Groom / transition a ticket
 
@@ -113,6 +122,49 @@ bounces.
 **Don't hand-move anything out of `doing/`** — a build owns it. If you need to
 stop a build, that's `ab` (or a human), not `mv`.
 
+## Icebox
+
+`icebox/` is work deliberately deferred, groomed or not, that nothing
+dispatches from. The first time it is needed, create it:
+
+```
+ab ticket state create icebox --about "Deferred on purpose; nothing dispatches from here"
+```
+
+Move a ticket in with `ab ticket move file-3 icebox`. To revive one, move it to
+`triage/` when it needs regrooming, or to `ready/` when its spec still holds.
+
+## Triage the backlog
+
+To run a pass over `triage/`:
+
+1. Run `ab ticket states` to see which destinations exist.
+2. For each ticket in `triage/`, read it with `ab ticket show <id>` and judge
+   whether its body meets the
+   [spec standard](../ab-guide/references/spec-standard.md).
+3. Move it to `ready/` if it conforms and should be built; to `icebox/` if it
+   should wait; to another existing category if one fits; otherwise leave it in
+   `triage/` and tell the user why.
+4. Report every move to the user in the session — id, title, destination, and
+   reason. A move leaves no comment on the ticket, so the report is the only
+   record of why.
+
+## Inventing categories
+
+Run `ab ticket states` before creating anything. Reuse an existing state whose
+purpose fits. Create a new one only for a recurring reason that no existing
+state covers, with a lowercase hyphenated noun name and a one-line `--about`
+purpose. `icebox` is the first worked example; `rejected` is a second:
+
+```
+ab ticket state create rejected --about "Considered and declined; kept for the record"
+```
+
+Never invent a second ready, doing, or done state, never move anything out of
+`doing/`, and never create states for a build's internal progress — the
+lifecycle belongs to the dispatcher. Remember that `ab ticket list` without
+filters still shows only the ready state, however many custom states exist.
+
 ## Rules
 
 - Never edit frontmatter to change state — the directory is the state.
@@ -132,7 +184,7 @@ listing under default config. That does not make `ready/` sufficient;
 unresolved blockers are an independent dispatch gate.
 
 No Linear lifecycle UI. Directory-based lifecycle operations (`ls`, `mv`, and
-the four state directories) are file-tracker-only. If this repo's
+the state directories) are file-tracker-only. If this repo's
 `autobuild.toml` sets `[tickets] source = "linear"`, do not apply that lifecycle
 guidance: state and labels live in Linear. The source-agnostic `ab ticket block`
 and `ab ticket unblock` commands still edit blocker relationships through the