@defrex/autobuild 0.12.0 → 0.13.0

package/skills/guide/SKILL.md

@@ -197,7 +197,9 @@ The distinctions that change an administrator's answer:
   agent turn or command already running. Missing, unreadable, malformed, and
   routing-invalid candidates retain that snapshot with deduplicated operator
   notice, and restoring a valid file resumes reload. Scoped phase CLI processes
-  still read the build worktree's branch-owned file.
+  still read the build worktree's branch-owned file. Dispatcher merge readiness,
+  resume, and execution recovery use the runner's pinned commands, verify, and
+  finalize configuration; builds without a pin retain the live fallback.
 - **Workspaces** are provisioned per build and remain the locally reachable
   execution context for that build.
 - **Ticket providers** (`linear`, `file`) sit behind one port; the dispatcher
@@ -215,6 +217,22 @@ The distinctions that change an administrator's answer:
   guidance and later dispatcher ticks retry. Without consent it remains open for
   ordinary `git diff` inspection; it has no review UI or image host.
 
+For moving a project between sources, follow the [ticket migration procedure](references/ticket-migration.md).
+
+## Independent hosted tickets
+
+Hosted tickets support local builds. Configure `[tickets] source = "hosted"`,
+`teamKey`, and `url`, or run `ab connect --tickets URL` to register the project,
+save its credential and publish ticket policy without changing the build store.
+Without `tickets.url`, tickets use the selected remote build service; local builds
+require an explicit ticket URL. No dispatcher is needed for ticket commands.
+Hosted defaults are `triage`, `ready`, `doing`, `done`; create/proposal use triage.
+Other sources still require readyState. Explicit state names retain their spelling.
+Legacy clients without independent policy retain uploaded configuration defaults.
+Harvest ticket grants are service-bound read/create authority; child phases are
+read-only and cannot publish policy. See [setup](references/setup.md) and the
+[ticket protocol](references/remote-ticket-protocol.md).
+
 ## `autobuild.toml` reference
 
 One declarative file at the repo root. **Declarative, not executable** —
@@ -737,6 +755,21 @@ exhaustion dispatch parks durably; bare `ab answer <slug>` and text guidance
 both grant a fresh budget, while abort terminates without retrying. Workspace
 failures owned by provider infrastructure recovery use only its existing budget.
 
+The dispatcher also applies a fixed, non-configurable limit of three consecutive
+executions that complete normally with exit code zero and no durable build
+progress. Execution start/end, runner attachment and workspace lifecycle
+bookkeeping do not count as progress. Pipeline, session, spec, publication/PR,
+observation and acknowledged operator facts reset the streak; infrastructure,
+budget and provider failures do not consume the allowance and retain their own
+retry limits. Before a fourth actionable launch, the dispatcher raises one
+setup-targeted `execution-no-progress` policy escalation naming the count and
+the next action it expected the runner to take. Waiting, paused and terminal
+builds are left parked, and pending operator commands remain executable.
+Answering that escalation with guidance or a bare `ab answer <slug>` retry grants
+three fresh executions. The guard is derived from durable facts, including on
+supervisor restart, and uses the ordinary watch, dashboard and operator API
+attention paths.
+
 For each repeat conflict, Autobuild compares the base merged by the latest
 completed reconcile with a fresh authoritative base snapshot. An advanced base
 proves the attempt lost a race and permits another reconcile regardless of the
@@ -788,13 +821,14 @@ 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 matches it case-insensitively to a state directory (`ready` → `ready/`). There is no any-state mode. |
+| `url` | selected build service | HTTPS URL (loopback HTTP allowed), no userinfo/query/fragment; hosted only | Ticket service independent of builds; required for local builds. |
+| `readyState` | hosted: `ready` | non-blank string; required for other sources | 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` and `hosted`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`) or an existing plugin configuration field. |
+| `teamKey` | — | required by `linear` and `hosted`, forbidden by `file`, allowed for plugins | The Linear team key (e.g. `"ENG"`), the captured prefix for new hosted ticket ids (`ENG-1`), or a plugin configuration field. Hosted numbers are project-local and continue across prefix changes; legacy ids remain aliases and readable inputs are case-insensitive. |
 | `claimedState` | — | optional nonempty string; forbidden by `file`, allowed for plugins | Workflow state `claim()` moves a ticket to when a build starts. |
-| `doneState` | hosted: `"Done"` | optional nonblank string | Project completion state and merged-ticket transition; hosted tickets only. |
+| `doneState` | hosted: `"done"` | optional nonblank string | Project completion state and merged-ticket transition; hosted tickets only. |
 | `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). |
-| `triageState` | — | optional, nonempty string | State the dispatcher hands tickets back to for human triage — spec-gate bounces, aborted builds, closed-unmerged PRs. Absent = Linear/hosted: Backlog; file/plugin: Triage. Must name a state the tracker actually has — a Linear team only has "Triage" when its triage feature is enabled. |
+| `triageState` | — | optional, nonempty string | State the dispatcher hands tickets back to for human triage — spec-gate bounces, aborted builds, closed-unmerged PRs. Absent = Linear: Backlog; hosted: triage; file/plugin: Triage. Must name a state the tracker actually has — a Linear team only has "Triage" when its triage feature is enabled. |
 | `proposalState` | — | optional, nonempty string | State observation harvest files approved proposals into. Absent = the resolved `triageState`, which keeps the human grooming gate. Setting it to `readyState` waives that gate: harvested proposals dispatch without being read. Keep it distinct from `triageState` — see below. |
 | `dir` | file: `.autobuild/tickets`; plugin: — | optional nonempty string; forbidden by `linear`, allowed for plugins | Root holding file state directories, or an existing plugin configuration field. |
 
@@ -1214,16 +1248,19 @@ transitions, so an invalid state fails with the
 source's known states. A missing id fails nonzero with an error naming both the
 id and configured source.
 
-Human-readable output is the default and must not be parsed for ids. Every
-subcommand accepts `--json`, which emits one bare JSON value and no prose: a
+Human-readable output is the default and must not be parsed for ids. The CRUD
+subcommands accept `--json`, which emits one bare JSON value and no prose: a
 `Ticket[]` for `list`, and the complete resulting `Ticket` for `create`,
 `update`, `block`, `unblock`, `show`, or `move`.
 
 ### Ticket assets
 
-A ticket asset is a file or folder attached to a ticket and stored in the
-BuildStore, never in the ticket source: a design export, reference screenshots,
-a sample payload. Each has a kind and a name.
+A ticket asset is a file or folder attached to a ticket: a design export,
+reference screenshots, or a sample payload. Hosted tickets store assets in their
+ticket service, independently of the build store; file tickets use native portable
+assets composed with legacy BuildStore attachments. Sources without native assets
+use the BuildStore. Existing service assets need no migration. Old local hosted-ticket
+assets are not moved and are not a fallback. Each has a kind and a name.
 
 - `ab ticket attach <id> <kind> <path> [--name <name>] [--json]` stores `<path>`
   (default name: its basename). Attaching the same kind and name again makes a
@@ -1235,7 +1272,10 @@ a sample payload. Each has a kind and a name.
 - `ab ticket asset get <id> <kind> <name> <dest> [--rev <n>]` downloads the
   exact bytes of the latest (or given) revision; `ab ticket asset rm <id> <kind>
   <name>` drops it from the current assets.
-- **Frozen at claim.** A claim pins the current revisions into the build. A
+- **Frozen at claim.** A claim pins the current revisions into the build.
+  Hosted revisions are copied into immutable snapshots in the build store,
+  preserving revision numbers and allowing reads without the ticket service.
+  Old pins without snapshots keep reading their original ticket rows. A
   later attach or remove leaves a running build alone; a human answer with
   `--revise-spec-from-ticket` pins again. `ab build asset get <slug> <kind>
   <name> <dest> [--rev <n>]` downloads what the build froze, also after it ends.
@@ -2038,3 +2078,43 @@ build phase, which is the criterion for membership (§16.3): `ab-spec` and
 `ab-tickets` are human/agent-facing pre-build surfaces, `ab-guide` is
 read-only reference including the setup handoff guidance, and `ab-operate` is
 the manual for the orchestrator role, which any agent may take on.
+
+## Revision-checked ticket writes
+
+Every ticket read includes an opaque `revision`. Pass it as `expectedRevision`
+(on MCP/operator requests) or `--expected-revision <opaque>` on `ab ticket update`,
+`move`, `block` and `unblock`. A stale write fails without changing anything and
+reports the current revision. Omission preserves unguarded behavior. Blocker
+checks cover the entire batch. Dispatcher moves remain unguarded and change the
+revision. Sources without guarded writes, including Linear, refuse supplied
+revisions rather than ignoring them.
+
+`ab ticket edit <id>` opens `$VISUAL`, falling back to `$EDITOR`, using TOML
+frontmatter and a Markdown body. Only title, body and labels are editable;
+id, blockers, creation key and reference comments are read-only. It saves only
+changed fields with the opening revision. Unchanged or formatting-only edits
+write nothing. On conflict, invalid input or editor failure, the error names an
+absolute file path containing the edited text. Read the current ticket and
+reapply the intended changes before retrying; conflicts are never merged.
+
+File and Linear revisions fingerprint title, body, canonical label/blocker sets
+and state; reverting identical content restores its fingerprint. File checks
+re-read immediately before writing, with the existing no-lock race window.
+Direct file edits and state-directory moves change revisions. File revisions also
+cover structured comments and portable attachments. Legacy file comments change
+the body; structured comments preserve it. Separate hosted comments do not change
+ticket revisions. Hosted revisions
+are monotonic decimal bigint strings, and checks run under the same row lock
+and transaction as all requested changes. Hosted reads return a coherent
+snapshot of fields, blockers and revision.
+
+Read before writing, and copy the opaque revision verbatim:
+
+```sh
+ab ticket show AUT-8 --json
+ab ticket update AUT-8 --title 'Revised title' --expected-revision '<revision from show>'
+ab ticket edit AUT-8
+```
+
+Use `expectedRevision` on MCP `tickets.update`, `tickets.move`, `tickets.block`
+and `tickets.unblock` with the revision from `tickets.get` or `tickets.list`.

package/skills/guide/references/operator-api.md

@@ -87,6 +87,7 @@ turn runner (a later ticket) is the only producer of turn facts.
 | `GET …/harvest/status` | Harvest gate, runs, steps, recovery, and attention projection. |
 | `GET …/builds/{slug}/artifacts/{kind}?rev=N` | Raw bytes (`application/octet-stream`) plus content-disposition and `X-Autobuild-Artifact-*` metadata headers. Omit `rev` for latest. |
 | `GET …/tickets?state=S&label=L` | `{states,tickets,diagnostics,criteria,triageState,readyState}`. The two lifecycle names come from effective repository configuration (including provider fallback). With no `state`, `criteria.state` is `triageState`; repeated `label` parameters narrow that state with AND filters. An explicit `state` selects that exact backend workflow state. |
+| `GET …/tickets/states` | Full state metadata `{name,tickets,about?}[]`, including empty states (`tickets.states` in MCP). |
 | `GET …/tickets/{id}` | `{ticket,blockers,build}`. Blockers include native `exists`/`resolved` status; `build` prefers an active matching repository build, otherwise the most recently updated one. |
 
 For artifact reads, an absent `rev` selects the latest revision. A supplied value
@@ -119,6 +120,7 @@ JSON bodies are strict: unknown fields are rejected.
 | `POST …/settings/auto-merge-default/toggle` | Empty body. |
 | `POST …/bulk-control` | `{"action":"pause"\|"resume"}`. The hold fact, intake fact, then eligible build events are written in that order. |
 | `POST …/harvest/control` | `{"action":"toggle-gate"}` or `{"action":"run","run":"…"}`. A run action is bound to that concrete projected run. |
+| `POST …/tickets/states` | `{name,about?}` → `{state,created}`; requires attributed operator identity (`tickets.state.create` in MCP). Hosted duplicate names are refused case-insensitively. |
 | `POST …/tickets` | `{"title":"…","body":"…","labels"?:[],"state"?:"…","blockedBy"?:[]}`; omitted state preserves the backend default. |
 | `PATCH …/tickets/{id}` | Any nonempty subset of `title`, `body`, and complete-replacement `labels`. Body bytes are not normalized. |
 | `POST …/tickets/{id}/move` | `{"state":"backend state name"}`. |
@@ -284,3 +286,8 @@ even with `--since`; live and backlog matches ignore routine outcomes and
 self-healing failures. A merge match uses the watch observation with
 `condition: "attention"`. Explicit `--event` globs remain event-only.
 Watch and wait preserve each other's cursor notification metadata.
+
+Hosted ticket tools resolve independent project ticket policy before legacy uploaded
+configuration. Queue, detail, state discovery and mutations work before any build
+or dispatcher run; detail reports a null matching build. Ticket policy publication
+never creates synthetic build or repository history.

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

@@ -485,6 +485,16 @@ does not apply. `{repo}` and `{id}` are percent-encoded path segments. Token
 authorization requires a credential for that registered project, or owner admin.
 The family is additive, so `REMOTE_STORE_PROTOCOL_VERSION` did not change.
 
+Hosted ticket attachments use the ticket service's existing repository-keyed
+asset routes with the ticket connection's URL and credential, independently
+of the build store. Names, revisions, tombstones and service limits are
+unchanged. Existing service attachments need no migration; old local
+attachments are not moved or used as a fallback. A claim or ticket spec re-pin
+copies exact revisions into immutable chunked repository artifacts in the
+destination build store. Build pins reference explicit snapshot manifests;
+build-scoped asset reads need no ticket credentials. Old pins without snapshot
+references keep their existing ticket-row lookup.
+
 A build also reads the assets it froze at its claim through its own build-scoped
 routes, authorized against the build's actual project. The
 server reduces the build's events to find the pinned revision, then returns that

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

@@ -67,6 +67,16 @@ must match the credential's project; mismatches are 403. Owner admin requests
 require this selector and registration is checked before configuration is read.
 Internal operator credentials remain forbidden on machine ticket routes.
 
+Hosted ticket attachments use the ticket service's existing repository-keyed
+asset routes with the ticket connection's URL and credential, independently
+of the build store. Names, revisions, tombstones and service limits are
+unchanged. Existing service attachments need no migration; old local
+attachments are not moved or used as a fallback. A claim or ticket spec re-pin
+copies exact revisions into immutable chunked repository artifacts in the
+destination build store. Build pins reference explicit snapshot manifests;
+build-scoped asset reads need no ticket credentials. Old pins without snapshot
+references keep their existing ticket-row lookup.
+
 The strict request envelope is:
 
 ```json
@@ -82,16 +92,37 @@ The strict request envelope is:
 
 `teamKey` remains required for older client compatibility. It and the optional
 `claimedState` / `createState` fields are ignored as policy inputs. The service
-loads the project's latest effective configuration from its repository journal
-and artifact bytes for every operation. Missing or invalid configuration returns
-an actionable 409; run the project's dispatcher to publish its configuration.
-There is no deployment-wide lifecycle fallback.
+loads the project's durable independent ticket policy. Project authority publishes
+version 1 policy through `POST /tickets/policy`, using the usual context/input
+envelope. The input contains only `version` and `tickets`: source, teamKey,
+readyState, triageState, claimedState, doneState, createState, proposalState and
+optional readyLabels. URL, secrets, and pipeline configuration are rejected.
+Only project or owner authority can publish. This does not append BuildStore
+history. Registration removal invalidates policy and grants from that registration.
+
+For compatibility, projects without independent policy use their latest uploaded
+dispatcher configuration with the old `Backlog`, `Doing`, `Done` defaults.
+New policy defaults are `triage`, `ready`, `doing`, `done`; create/proposal follow
+triage. States are persistent project data, including empty states and optional
+one-line purposes. Configured role names always exist; removed roles remain as
+custom states and keep their tickets. Explicit settings preserve state spelling.
+State lookup prefers an exact match, then a unique case-insensitive match;
+unknown or ambiguous names are refused. Lists order configured triage, ready,
+doing, done first (deduplicated), then other names alphabetically.
+
+`[tickets] url` selects the ticket service independently of the build store;
+otherwise the selected remote build store is used. A local build store requires
+an explicit ticket URL. Credentials are resolved for that selected service.
+`ab connect --tickets URL` registers and publishes policy before any dispatcher run.
 
-Hosted lifecycle defaults are triage `Backlog`, claimed `Doing`, done `Done`,
-and create/proposal equal to triage. `readyState` is required. The allowed states
-are the distinct union of these configured roles, including custom create and
-proposal states; roles may overlap. Historical states remain readable unchanged.
-`tickets.doneState` controls completion and the dispatcher's merged transition.
+`POST /tickets/grants` issues, renews or revokes short-lived, digest-stored ticket
+grants. Project authority issues runner grants scoped to project and execution;
+runners may issue only read-only phase children bound to themselves. Runner grants
+allow read and create; phase grants allow read only. Policy, claim, moves, comments,
+updates, blocker changes, BuildStore, and credential administration are denied.
+AB_TICKET_URL and AB_TICKET_TOKEN carry this authority separately from AB_STORE and
+AB_TOKEN. Revocation, expiry, parent revocation and registration changes invalidate
+grants. Existing combined-service BuildStore delegation remains supported.
 
 The service never contacts Linear or relays external trackers. If the project's
 source is Linear, file or another non-hosted source, machine HTTP, operator and
@@ -111,6 +142,8 @@ The operation names and `input` values are:
 
 | Operation | Input | Successful response |
 |---|---|---|
+| `states` | `{}` | `{name, tickets, about?}[]`, including empty states |
+| `add-state` | `{name, about?: string}` | `{state: {name,tickets,about?}, created: boolean}` |
 | `list-ready` | `{labels?: string[], state?: string}` | `TicketListing` |
 | `get` | `{id}` | `Ticket \| null` |
 | `claim` | `{id}` | `{claimed: boolean}` |
@@ -132,6 +165,35 @@ Ticket body strings are opaque. Clients, JSON handling, the service, and the
 database backend must not trim or normalize bytes, newlines, Unicode, blank
 lines, or trailing whitespace.
 
+## Readable ticket identity
+
+New hosted tickets use `<teamKey>-<n>`, for example `ENG-1`. The effective
+project configuration supplies the literal prefix; the request's `teamKey`
+does not choose it. Numbers start at 1 in each project, increase atomically
+across concurrent creates, and are never reused after deletion. Projects sharing
+a team key have independent counters. Changing `teamKey` affects only future
+ids and continues the same numbering; existing ids retain their captured prefix.
+
+Every ticket operation, CLI command, MCP tool and blocker input accepts readable
+ids in any letter case. Legacy storage ids (such as `ticket-<uuid>`) remain
+aliases, including references in existing builds, harvest records and assets.
+Current ticket and blocker output uses the canonical readable id. The exception
+is `dependency-states`: each result's `id` echoes the requested id for correlation,
+while its `blockedBy` edges are canonical. Raw historical events and artifacts
+remain unchanged. These rules apply only to hosted tickets, not file or Linear ids.
+
+Upgrade the service with its environment-aware migration command before serving
+requests. The transactional migration preserves storage keys and assigns existing
+tickets numbers in `(created_at, id)` order within each project. It first resolves
+legacy team ownership, then reads each populated project's current independent
+ticket policy. Projects without that policy use their selected effective
+configuration through the configured blob backend. Independent-policy projects
+need no uploaded config or blob access. Missing or invalid fallback config,
+missing `teamKey`, or inaccessible required blobs abort the entire migration
+unchanged with a project diagnostic. Restore that config/blob access and rerun;
+an ownership assignment alone cannot supply a readable prefix. Empty projects
+need no config lookup. Re-running a completed migration does not renumber tickets.
+
 ## Errors and conformance
 
 Errors are JSON `{ "error": string, "kind": "validation" | "not-found" |
@@ -170,3 +232,83 @@ project removal are also checked before parsing or source construction.
 
 Ticket admission and assets use the authenticated project, including for
 delegated harvest grants.
+
+Custom state creation uses `/^[a-z][a-z0-9-]{0,39}$/`; an optional purpose must
+be one nonblank line. A duplicate in any letter case is refused without
+changing purpose. `add-state` requires project or owner machine authority;
+ticket grants and harvest delegations can read states but cannot create them.
+Request context cannot supply lifecycle policy or insert another project's
+states. These operations use the existing wire version and strict envelopes.
+
+## Revision-checked ticket writes
+
+Every ticket read includes an opaque `revision`. Pass it as `expectedRevision`
+(on MCP/operator requests) or `--expected-revision <opaque>` on `ab ticket update`,
+`move`, `block` and `unblock`. A stale write fails without changing anything and
+reports the current revision. Omission preserves unguarded behavior. Blocker
+checks cover the entire batch. Dispatcher moves remain unguarded and change the
+revision. Sources without guarded writes, including Linear, refuse supplied
+revisions rather than ignoring them.
+
+`ab ticket edit <id>` opens `$VISUAL`, falling back to `$EDITOR`, using TOML
+frontmatter and a Markdown body. Only title, body and labels are editable;
+id, blockers, creation key and reference comments are read-only. It saves only
+changed fields with the opening revision. Unchanged or formatting-only edits
+write nothing. On conflict, invalid input or editor failure, the error names an
+absolute file path containing the edited text. Read the current ticket and
+reapply the intended changes before retrying; conflicts are never merged.
+
+File and Linear revisions fingerprint title, body, canonical label/blocker sets
+and state; reverting identical content restores its fingerprint. File checks
+re-read immediately before writing, with the existing no-lock race window.
+Direct file edits and state-directory moves change revisions. File revisions also
+cover structured comments and portable attachments. Legacy file comments change
+the body; structured comments preserve it. Separate hosted comments do not change
+ticket revisions. Hosted revisions
+are monotonic decimal bigint strings, and checks run under the same row lock
+and transaction as all requested changes. Hosted reads return a coherent
+snapshot of fields, blockers and revision.
+
+### Guarded mutation transport
+
+`POST /tickets/mutate-if-revision` accepts the usual authenticated context and
+`input: { id, expectedRevision, mutation }`. Mutation is one of
+`{ kind: "update", patch: { title?, body?, labels? } }`,
+`{ kind: "transition", state }`, or
+`{ kind: "blockers", operation: "block" | "unblock", ids: string[] }`.
+Unknown keys and empty patches are refused. Success returns `{ ok: true }`.
+A revision conflict returns HTTP 409 with `kind: "conflict"`, `error`, `id`,
+`expectedRevision` and `currentRevision`. Delegated credentials retain existing
+permissions: none of the guarded mutation variants grants additional access.
+Ticket responses include `revision` only when the request advertises
+`x-autobuild-ticket-revisions: 1`. The current hosted client sends this header
+on every request and requires revision-bearing responses. Released clients
+through 0.12.x omit the header and retain their strict decoder's original
+response shape on get, list-ready and create. This explicit capability also
+supports new source checkouts that still report version 0.12.0; version alone
+cannot distinguish them from released clients. Unknown capability values do
+not opt in. Clients before 0.11 also omit the existing resolution projections.
+The capability does not change authentication, authorization or the remote
+BuildStore protocol version.
+
+## Requested ids for migration
+
+Create options accept optional `requestedId: string` alongside `state` and
+`idempotencyKey`. Older clients omit it and responses are unchanged. Unsupported
+sources reject supplied ids; Linear is not an import target. File sources keep
+filesystem-safe ids exactly and never overwrite an occupied id.
+
+Hosted sources preserve only literal own-team `<teamKey>-<n>` ids, where `n` is a
+positive canonical decimal within PostgreSQL bigint bounds. For example,
+`AUT-706` in team `AUT` keeps 706; `OTHER-706`, `AUT-01` and `AUT-0` use ordinary
+allocation. Overflow canonical numbers are rejected. A matching creation key is
+adopted before occupancy checks. A kept number belonging to a different ticket
+fails without replacing it. Creation and counter advancement share the existing
+project transaction and counter lock. Later automatic numbers exceed both the
+counter and highest occupied number; importing a lower number never lowers the
+counter. Requested ids require project or owner authority. Ticket grants and
+delegated credentials receive 403 for create options containing `requestedId`,
+before source construction. Their ordinary create grants remain unchanged.
+
+See the [migration procedure](ticket-migration.md) for preflight, state mapping,
+resumption and portable file records.

package/skills/guide/references/setup.md

@@ -398,13 +398,13 @@ the verifier does not fix it.
 ### Project-scoped hosted tickets
 
 Hosted ticket queues belong to the credential's registered repository, even
-when projects share a team key. The latest uploaded effective `[tickets]`
-configuration owns lifecycle: hosted defaults are Backlog / Doing / Done,
-`readyState` is required, `doneState` customizes completion, and create/proposal
-default to triage. The union of configured roles is allowed; roles may overlap.
-Owner admin requests require an explicit registered `context.repo`; project
-credentials cannot select another project. Missing effective configuration is
-an actionable refusal: run the project's dispatcher to publish it.
+when projects share a team key. Independent project ticket policy owns lifecycle:
+new defaults are triage / ready / doing / done, with create/proposal following
+triage. Explicit names retain their spelling; doneState customizes completion.
+`ab connect --tickets URL` publishes policy before dispatch. Older clients without
+independent policy retain their uploaded dispatcher configuration and legacy defaults.
+Owner admin requests require an explicit registered context.repo; project credentials
+cannot select another project. See [local builds with hosted tickets](#local-builds-with-hosted-tickets).
 
 The service never contacts Linear. Projects with external sources (including
 file and Linear) keep using those sources directly through their dispatcher;
@@ -447,3 +447,29 @@ require the running service's blob backend, access mode, credentials and prefix
 (`AB_BLOB_PREFIX`), not just PostgreSQL access. `deploy:build` inherits this
 environment and migration failure stops Next build. Fresh databases, empty v1
 queues and v2 reruns stay SQL-only and do not initialize blob storage.
+
+## Local builds with hosted tickets
+
+Hosted tickets do not require hosted builds. Set `[tickets] source = "hosted"`
+and `teamKey = "ENG"`, then run `ab connect --tickets https://your-service.example`.
+Approve the project in the browser. This saves a service-scoped credential and
+`[tickets] url` while leaving `[store]` unchanged. Ticket commands work immediately,
+before any dispatcher runs. `ab connect` reports every service and whether it serves
+builds, tickets, or both. Use `ab disconnect --tickets` to revoke ticket access;
+when services differ use `--builds` to select build access. Shared uses share one
+credential, so disconnecting either shared use affects both.
+
+Ticket URL selection is `[tickets] url`, then the selected build service (including
+AB_STORE or a supported --store override). With local builds, `[tickets] url` is
+required. Builds, events, artifacts, and harvest journals remain in the local store.
+The service stores ticket records, project ticket policy, and restricted ticket
+grants. Normal project clients synchronize current `[tickets]` policy before use;
+failed synchronization fails the operation. Harvest grants can read and create;
+phase grants can only read. Neither can change policy or access BuildStore routes.
+
+New hosted policy defaults to `triage`, `ready`, `doing`, `done`, with creation and
+harvest proposals in `triage`. Explicit state names preserve their spelling.
+To retain earlier names configure `triageState = "Backlog"`,
+`claimedState = "Doing"`, `doneState = "Done"`, and the desired `readyState`.
+Existing ticket rows are never renamed. Older combined-service clients continue
+using the uploaded dispatcher configuration until independent policy is published.

package/skills/guide/references/ticket-migration.md

@@ -0,0 +1,64 @@
+# Moving a project between ticket sources
+
+Export and import use the ordinary file ticket layout. They operate on tickets
+and current attachments through the ticket source; neither command contacts the
+forge. File and hosted sources support import. Linear supports export only.
+
+1. Pause intake and stop other ticket writers for the cutover. Import preflight
+   does not reserve numbers against concurrent writers.
+2. With the old `[tickets]` configuration, run `ab ticket export /path/to/export`.
+   The destination must be absent or empty. Export reads every state, including
+   archived Linear tickets and empty discoverable states, and publishes the
+   directory only after all reads succeed. Back up the target tracker too.
+3. Configure the new `[tickets]` source, or use `ab connect --tickets URL` for a
+   hosted ticket service. Keep the export directory intact.
+4. Run `ab ticket import /path/to/export`. Inspect its printed ticket and state
+   mappings and `/path/to/export/.ab-import-map.json`.
+5. Inspect ticket bodies, labels, blockers, comments and attachments in the new
+   source. Confirm lifecycle configuration and the ready gate, then resume intake.
+
+Both commands also accept
+`--store <ref>` to reach legacy BuildStore attachments. Keep the old store available
+through export when file or Linear tickets have attachments there.
+
+State directory names use lowercase letters, digits and hyphens, start with a
+letter and contain at most forty characters. Export maps `In Progress` to
+`in-progress`, `Backlog` to `backlog`, and `Done` to `done`. It retains each ticket's
+state rather than assigning lifecycle roles. Distinct names that collapse to the
+same directory fail before publication. The hidden `.ab-migration.json` records
+original display names and the state map. Import also accepts ordinary legacy
+file layouts: it reuses exact or unique case-insensitive target states before
+normalizing new names. A seeded `done` satisfies `Done`; absent `In Progress`
+creates `in-progress`. Ambiguous matches and colliding state maps fail preflight.
+
+File targets retain source ids. Hosted targets keep canonical own-team ids:
+`AUT-706` imported into team `AUT` stays `AUT-706`. Other ids receive numbers above
+all existing and preserved incoming numbers. Known clashes with unrelated tickets
+are reported together before any target state, ticket, comment or asset write.
+Content similarity and stale mapping files never establish identity.
+
+Creation keys establish identity. Exports retain existing keys and assign keys to
+legacy tickets. Importing an ordinary file layout first saves a hidden migration
+identity and keys in that input directory. Preserve this file and the input across
+retries. After interruption, rerun the same command: committed creates are adopted
+by key even if their mapping write failed. Adopted bodies and other fields are not
+overwritten. Missing blockers and comments are replayed, and unchanged attachments
+do not create another revision. Comments are deduplicated by exact body, so two
+identical source comment bodies produce one target comment. Original authors and
+timestamps remain in the export; imported comments use the target's metadata.
+
+Portable records use TOML frontmatter between `+++` fences and an unchanged
+Markdown body. Alongside `id`, `title`, `labels`, `blockedBy` and `idempotencyKey`,
+optional `comments` contain `body`, `createdAt` and optional `author`. Optional
+`attachments` contain `kind`, `name`, `layout` (`file` or `tree`) and `entries`:
+`{ type = "dir", path = "empty" }` or
+`{ type = "file", path = "image.png", base64 = "…" }`. Common asset limits and
+path validators apply. Only current attachment contents travel, including binary
+files and empty directories; historical revisions do not. The exported directory
+works directly as a file source, without its migration manifest or original store.
+File source revision history stays in its hidden `.ab-assets` directory.
+
+Legacy records without `comments` retain their Markdown comment append behavior;
+export never interprets Markdown headings as structured history. New file tickets
+use structured comments and preserve their body when a comment is added. There is
+no continuous sync, assignee migration, state history or build-history migration.

package/skills/tickets/SKILL.md

@@ -9,6 +9,16 @@ The local ticket tracker is a directory of markdown files. `ls` and `mv` are
 the state/backlog UI; source-agnostic `ab ticket` commands create and edit
 content and blocker relationships. The default file source needs no secret.
 
+## Hosted ticket ids
+
+When `[tickets].source = "hosted"`, use readable ids such as `ENG-12` with
+`ab ticket show`, `update`, `move`, `block`, and `unblock`. Inputs accept any
+letter case and old UUID ids remain aliases. Output shows canonical readable
+ids; blocker references use the same identity. Numbering belongs to each project
+and never resets or reuses deleted numbers. A `teamKey` change affects future
+prefixes only. File and Linear id rules are unchanged. See the
+[hosted ticket protocol](../ab-guide/references/remote-ticket-protocol.md).
+
 ## Where it lives
 
 `.autobuild/tickets/` by default (if `autobuild.toml` has a `[tickets] dir`,
@@ -189,3 +199,64 @@ the state directories) are file-tracker-only. If this repo's
 guidance: state and labels live in Linear. The source-agnostic `ab ticket block`
 and `ab ticket unblock` commands still edit blocker relationships through the
 configured source.
+
+## Hosted ticket states
+
+For `[tickets].source = "hosted"`, states are project-owned service data.
+Run `ab ticket states` before creating a state, and reuse an existing purpose
+when it fits. `ab ticket state create icebox --about "Deferred work"` creates
+an empty state with an optional one-line, nonblank purpose. Custom names use
+one to forty lowercase letters, digits, or hyphens, starting with a letter.
+Hosted creation refuses an existing name in any letter case and never replaces
+its purpose; file creation remains idempotent and can update the purpose.
+
+Use `ab ticket create --state <name>`, `ab ticket move <id> <name>`, and
+`ab ticket list --state <name>` with any existing state. Unknown states are
+refused with the available names. Configured states are added automatically;
+former configuration roles remain custom states with their tickets intact.
+Listing puts the configured triage, ready, doing, and done roles first, then
+other states alphabetically, including empty states and purposes. Configured
+names keep their spelling; lookup prefers an exact match, then a unique
+case-insensitive match. States belong to one project.
+
+The directory `ls` and `mv` instructions above apply only to the file source.
+For MCP, use `tickets.states` and `tickets.state.create`; the latter requires
+an attributed operator identity and normal project authorization.
+
+## Revision-checked ticket writes
+
+Every ticket read includes an opaque `revision`. Pass it as `expectedRevision`
+(on MCP/operator requests) or `--expected-revision <opaque>` on `ab ticket update`,
+`move`, `block` and `unblock`. A stale write fails without changing anything and
+reports the current revision. Omission preserves unguarded behavior. Blocker
+checks cover the entire batch. Dispatcher moves remain unguarded and change the
+revision. Sources without guarded writes, including Linear, refuse supplied
+revisions rather than ignoring them.
+
+`ab ticket edit <id>` opens `$VISUAL`, falling back to `$EDITOR`, using TOML
+frontmatter and a Markdown body. Only title, body and labels are editable;
+id, blockers, creation key and reference comments are read-only. It saves only
+changed fields with the opening revision. Unchanged or formatting-only edits
+write nothing. On conflict, invalid input or editor failure, the error names an
+absolute file path containing the edited text. Read the current ticket and
+reapply the intended changes before retrying; conflicts are never merged.
+
+File and Linear revisions fingerprint title, body, canonical label/blocker sets
+and state; reverting identical content restores its fingerprint. File checks
+re-read immediately before writing, with the existing no-lock race window.
+Direct file edits and state-directory moves change revisions. File comments
+change the body and revision; separate hosted comments do not. Hosted revisions
+are monotonic decimal bigint strings, and checks run under the same row lock
+and transaction as all requested changes. Hosted reads return a coherent
+snapshot of fields, blockers and revision.
+
+Read before writing, and copy the opaque revision verbatim:
+
+```sh
+ab ticket show AUT-8 --json
+ab ticket update AUT-8 --title 'Revised title' --expected-revision '<revision from show>'
+ab ticket edit AUT-8
+```
+
+Use `expectedRevision` on MCP `tickets.update`, `tickets.move`, `tickets.block`
+and `tickets.unblock` with the revision from `tickets.get` or `tickets.list`.

package/templates/hosted-service/package.json

@@ -4,8 +4,8 @@
     "build": "ab-hosted-service-build"
   },
   "dependencies": {
-    "@defrex/autobuild-hosted-store-service": "0.12.0",
-    "@defrex/autobuild": "0.12.0",
+    "@defrex/autobuild-hosted-store-service": "0.13.0",
+    "@defrex/autobuild": "0.13.0",
     "next": "16.1.6",
     "react": "19.2.4",
     "react-dom": "19.2.4"