@defrex/autobuild 0.12.0 → 0.14.0

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

@@ -37,7 +37,7 @@ headers, or available backend.
   `[store] url` (in that precedence order, before the local default); the shipped client appends the routes below.
 - Every `/builds`, `/repos`, and `/sessions` request sends
   `X-Autobuild-Version` with the exact client package version and
-  `X-Autobuild-Protocol-Version` with the remote protocol version (`3` in this
+  `X-Autobuild-Protocol-Version` with the remote protocol version (`4` in this
   distribution). Before authentication,
   body parsing, or resource lookup, the server validates the release-line window and known protocol identity.
   Unsupported or missing values receive `409 {"kind":"conflict","error":"…"}`;
@@ -355,6 +355,74 @@ 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.
 
+### Named reducer values
+
+`POST /builds/{slug}/reducer-values` and
+`POST /repos/{repo}/reducer-values` accept at most 4 KiB of JSON:
+
+```json
+{"reducer":"dispatchStatus","args":{"run":"run-a"}}
+```
+
+The response is `200 {"version":2,"cursor":123,"value":{...}}`. Only the
+finished JSON answer is returned, with no accumulator or raw-log bundle. `cursor`
+is the authoritative prefix included in the answer, not a guarantee to include
+appends concurrent with the request. Every call checks durable progress and
+persisted state; parallel instances may safely advance the same checkpoint.
+Snapshots are disposable caches: deletion, corruption, wrong versions and
+unreadable cache storage cause replay. Log read failures remain errors.
+
+The executable catalog is `kernel/reducer-registry.ts`. All requests reject
+unknown names, excluded reducers, wrong scopes and invalid/extra arguments with
+`400 validation`. A missing resource is `404`, project and delegated authority
+checks are the same as other reads, and unsupported methods remain unavailable.
+The operation is read-only authority even though its HTTP verb is POST and its
+internal cache may advance. It does not accept caller-supplied state. This is an
+additive protocol route: historical snapshot and event handlers and the supported
+client version window are unchanged.
+
+| Scope | Reducers with no arguments |
+| --- | --- |
+| Build | `executionNoProgress`, `summaryRequests`, `build`, `buildDigest`, `currentPrAttachments`, `pendingPrAttachmentReclaims`, `openExecution`, `lastExecutionOutcome`, `infrastructureFailureReset`, `openWorkspace`, `setupStreak`, `openBuildWorkspace`, `currentDeferralObservation`, `dashboardFacts`, `pinnedAssets`, `buildDelegation` |
+| Repository | `harvest`, `dispatchSettings`, `sandboxStates`, `openHarvestExecutions`, `autoMergeDefault`, `effectiveConfig`, `harvestDelegation` |
+
+| Reducer | Scope | Required arguments |
+| --- | --- | --- |
+| `dispatchStatus`, `openTick` | Repository | `run`: nonempty string |
+| `dispatchFailureBudget` | Build | `infrastructureOwnsWorkspace`: boolean |
+| `phaseFailures` | Build | `phase`: valid phase name; `round`: nonnegative integer |
+
+Arguments are canonicalized into the cache identity; variants never reuse one
+another's accumulator. `effectiveConfig` returns an object with optional `run`
+and `reference: {kind, rev}`. Absence is distinct from an unreadable referenced
+artifact. Delegation values contain semantic lifecycle facts indexed by prefixed
+identifiers, not authorization decisions; request time and grace expiry are
+always evaluated against those facts on the service.
+
+Each remaining registered reducer is explicitly excluded:
+
+| Reducers | Reason |
+| --- | --- |
+| `journalView`, `repositoryStateEvents`, `dispatchFrontend` | Raw repository event lists |
+| `session` | Operator-session log scope |
+| `publicationState` | Selector functions in finished value |
+| `logIndex` | Maps and Sets in finished value |
+| `hostedPrAttachments` | Map as finished value |
+| `summaryBoundary`, `ticketSourceHealth`, `frozenPrImageHost`, `publishedBranchHead`, `verifyDiffBase`, `recordedBaseSha`, `baseBranch`, `provisionMarker`, `recoveryCheckpoint` | Existing finished contract can return top-level `undefined`, which is not JSON |
+
+`GET /repos/{repo}/state-events` is **deprecated**. Its response remains unchanged
+for supported clients, including the current dispatcher run's event tail. It is
+the compatibility exception to flat event-row reads; new callers should request
+named values. The current product no longer loads or writes raw-tail snapshots.
+
+The `value.*` snapshot namespace is reserved for the adapter's private value
+checkpoint hooks. Public snapshot GET and PUT requests for this prefix return
+`400 validation`, including requests made with delegated or administrator
+credentials. Adapter snapshot APIs reject the same names. Ordinary snapshot
+names retain their existing behavior. The value cache key format is versioned;
+checkpoints from the former publicly writable format are ignored and rebuilt
+from the log after upgrading.
+
 ### Reducer snapshots
 
 A reducer snapshot is one registered reducer's serialized state as of a log
@@ -485,6 +553,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
@@ -1126,7 +1204,7 @@ Four shipped behaviors do not add `BuildStore` routes:
   store lifecycle; there is no close endpoint.
 - `GET /health` is outside the `BuildStore` interface. It is always open and
   returns exactly `200 {"ok":true,"autobuildVersion":"<package>",
-  "protocolVersion":"3", "supportedClientRange":{"minVersion":"0.9.0",
+  "protocolVersion":"4", "supportedClientRange":{"minVersion":"0.9.0",
   "maxVersionExclusive":"0.12.0"}}`. It reports HTTP-process availability and identity,
   not a deeper backing-store transaction or migration check.
 
@@ -1203,3 +1281,17 @@ require a project credential and operate only on its own identity; admin and
 internal operator credentials cannot impersonate self-service. All protocol
 responses are no-store/no-referrer. Connection commands are unavailable in
 build/harvest sessions.
+
+### Repository tick telemetry (protocol 4)
+
+`POST /repos/:repo/tick/begin` accepts `{holder}` and returns the actual start
+ timestamp, or null when the unexpired repository lease does not match.
+`POST /repos/:repo/tick/finish` accepts `{holder, completion, events}`. Completion
+is `{outcome:"completed", counters}` or `{outcome:"failed", error}`; events is
+empty for a quiet success or a matching dispatcher start/terminal pair for that
+holder. The validated batch and finished telemetry commit atomically. The reply
+is `{observation, events}` with assigned envelopes, or null on fencing failure.
+These operations never renew the lease. Repository records optionally expose
+`tick: {run, open?: {startedAt}, finished?: {run, startedAt, completedAt, ...completion}}`.
+They retain the previous completion while a new tick is open and after lease
+release. Build and session credentials cannot mutate repository ticks.

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.14.0",
+    "@defrex/autobuild": "0.14.0",
     "next": "16.1.6",
     "react": "19.2.4",
     "react-dom": "19.2.4"