@defrex/autobuild 0.11.0 → 0.13.0

package/skills/operate/SKILL.md

@@ -24,20 +24,83 @@ after them apply to both.
 
 ## Running locally with the `ab` CLI
 
-Run the commands below from the repository root. Each acts with the operator's
-authority, so say what you are doing before you do anything destructive.
+Each command acts with the operator's authority, so say what you are doing
+before you do anything destructive.
+
+### Resolve the local invocation first
+
+Before your first Autobuild command, read the repository's package manifests
+and package-manager evidence. A direct `@defrex/autobuild` declaration in
+`dependencies` or `devDependencies` requires the repository's installed
+version. The manifest's own `name` and a transitive dependency are not declarations.
+
+Determine the package manager from `packageManager` and the lockfile:
+`bun.lock` / `bun.lockb`, `package-lock.json` / `npm-shrinkwrap.json`,
+`pnpm-lock.yaml`, or `yarn.lock`. Resolve workspace context from the manifest
+declaring the dependency and the repository's package-manager configuration.
+If evidence conflicts or cannot establish the manager, diagnose and tell the
+operator instead of guessing.
+
+Verify that the dependency is already installed and that its installed package
+exposes the `ab` binary you will execute. For node_modules installs, verify
+that `./node_modules/.bin/ab` resolves to that installed
+`@defrex/autobuild` package, not another package or a global binary. For Yarn
+PnP, use Yarn's installed dependency and binary evidence to establish ownership.
+Run from the resolved repository/workspace directory:
+
+| Package manager | Local-only invocation |
+| --- | --- |
+| Bun | `bun run ./node_modules/.bin/ab …` |
+| npm | `npm exec --offline --no --call './node_modules/.bin/ab …'` |
+| pnpm | `pnpm exec ./node_modules/.bin/ab …` |
+| Modern Yarn | `yarn run --binaries-only ab …` |
+| Yarn Classic | `yarn run ab …` |
+
+Replace the ellipsis with CLI arguments; for npm they go inside the quoted
+call, with appropriate shell quoting. Do not add `--package` or an inferred
+package name. The explicit path prevents global PATH fallback, and npm's
+offline/no flags prevent registry installation. Modern Yarn's binary-only
+selection supports installed PnP dependencies without assuming node_modules.
+Before using Yarn Classic, verify its installed local binary and check that
+`scripts.ab`, `scripts.preab`, and `scripts.postab` cannot intercept the
+command. Report a script conflict instead of executing it.
+
+These forms execute an already-installed dependency. A missing dependency,
+unavailable binary, or failed local execution must be reported to the operator;
+never hide it with global fallback or install dependencies automatically.
+Never use bare `bunx ab`, `npx ab`, `dlx`, or other registry-fetching
+variants: the registry package named `ab` is not Autobuild. Offline cache
+availability alone does not prove a local installation.
+
+Only when no local declaration exists may you use global `ab`. In either
+case run the resolved invocation with `--version` and report the invocation,
+working directory, and actual version when you start orchestrating.
+
+Every `ab …` example in this skill means this resolved invocation, run from
+the same resolved working directory.
 
 ### Watch for attention events
 
-`ab watch --json` streams the attention set (escalations, failures, finalize,
-PR conflicted/merged/closed, build completed/aborted) as newline-delimited
-records. Every record carries a `cursor`; a bounded watch ends with a trailing
-`{"cursor": …}` line. Resume with `--since <cursor>` and every event after it
-is delivered exactly once, including events that landed while nothing was
-watching. Name slugs to watch only those builds; with none, every active build
-(including ones created later) and repository attention are watched. Named watches need `--repository` to also receive repository attention. `--event <glob>` replaces the
-default filter, `--timeout <dur>` bounds it (default 30 minutes, `0` is
-unbounded), `--count <n>` ends it after n records.
+`ab watch --json` is the standing monitor. Keep its default filter: every
+record calls for action. It reports build escalations and merge decisions,
+harvest escalations/recovery exhaustion, rejected configuration, reloads needing
+restart, abnormal dispatcher stops/loss, degradation past reset (15 minutes
+without reset), and five minutes of continuous tick failures. Advertised resets
+wait for a post-reset tick to finish before requiring action; ordinary recovery
+on that retry stays silent. Source grace and cooldown-driven failures do not
+start the tick-failure clock. Routine outcomes and self-healing failures stay silent.
+
+Every record carries a cursor; bounded watches end with a bare `{"cursor": …}`
+line. Resume with `--since <cursor>`. Named watches end when all named builds
+are terminal; add `--repository` for repository attention. With no slugs all
+active builds and repository attention are included. Reconcile status after
+arming because historical build attention is silently baselined.
+
+Add an extra monitor only for an identified need, such as an operator asking
+to hear when a particular build merges or an outcome triggering follow-up work.
+Scope it to named slugs and explicit `--event` globs (for example,
+`ab watch my-build --event pr.merged --json`), and retire it when that need ends.
+An extra monitor supplements the default standing watch.
 
 `ab wait [<slug>...] (--for <condition> | --event <glob>) [--since <cursor>] [--json]`
 blocks until a condition holds and prints one record. `--for` state conditions
@@ -51,7 +114,10 @@ bare `{"cursor": …}` to resume from.
 
 Run long watches and waits in whatever background or monitor facility your
 harness provides, so the session stays responsive and you are woken when they
-emit. Never block a foreground command for their whole duration.
+emit. Use precisely the same resolved invocation and working directory as
+foreground commands, including inside background shells and harness monitors.
+Do not rely on a shell alias or function that those facilities may lose.
+Never block a foreground command for their whole duration.
 
 Ticket-source degradation records mean dispatch intake cannot evaluate the source;
 existing builds may still advance. Inspect `ab repository status --json` for the
@@ -59,7 +125,7 @@ active cause, operation, message, and expected reset. Reset times are advisory;
 recovery means reads actually succeeded. Allow the existing cooldown and retry
 behavior, investigate persistent ready-scan failures or a condition still active
 after its reset estimate, and keep watching through recovery. Empty builds do
-not establish idle intake; repeatedly restarting dispatch does not clear it.
+not establish idle intake; diagnose persistent trouble and report it to the operator.
 
 Repository records have null build and state. Handle them with repository
 status rather than build commands, keep their cursor, and re-arm. A legacy
@@ -69,8 +135,8 @@ cannot recover its earlier interval: reconcile current repository status.
 attention watch.
 
 
-Check dispatcher liveness with `ab repository status --json` before starting another
-`ab dispatch`, and after a watch timeout or `dispatcher.lost` observation. Do not
+Check dispatcher liveness with `ab repository status --json` after a watch
+timeout or `dispatcher.lost` observation, or when dispatch appears unhealthy. Do not
 use process lists to decide whether a dispatcher owns this repository. The
 `dispatcher` projection distinguishes `held` (an unexpired lease), `lost`
 (expired ownership without a recorded stop), `stopped`, and `absent`. Its holder
@@ -84,7 +150,8 @@ read-only observation: `{repo, build:null, state:null, observation:{type:
 "dispatcher.lost", run, observedAt, leaseExpiresAt, ...identity}, cursor}`.
 It has no durable event envelope. Keep its cursor just as for event records;
 resuming it suppresses repeated loss reports for that run. Inspect repository
-status before deciding how to recover; watch never restarts a dispatcher.
+status to diagnose the condition and report dispatcher trouble to the operator.
+Neither a loss observation nor a later retry authorizes dispatcher intervention.
 
 ### Keep watching until the work is done
 
@@ -92,7 +159,7 @@ Checking once is not shepherding. When you take responsibility for builds:
 
 1. Record the set you are shepherding (`ab builds --all --json`, or the slugs
    you were given).
-2. Arm an event-only watch and keep its cursor:
+2. Arm the default standing watch and keep its cursor:
    `ab watch --json --since <cursor>` (or named slugs with `--repository`) (omit `--since` the first
    time). Events are delivered exactly once, so a build that already finished
    is never replayed. Do not loop on `ab wait --for terminal|attention|…`:
@@ -109,12 +176,12 @@ Checking once is not shepherding. When you take responsibility for builds:
    every timeout or legacy-cursor attachment. Reading status after arming leaves no gap — anything earlier shows in
    the status, anything later arrives as an event. Treat a terminal status
    (merged, closed, aborted) as that build's outcome, and an open escalation
-   or failed phase as attention to handle now.
+   or merge decision as attention to handle now.
 4. When a watch returns records, react: read the record, inspect the build,
-   answer or escalate; for a repository record inspect repository status and act
+   resolve attention using the shared rules; for a repository record inspect repository status and act
    on its condition without assuming a build slug. Then re-arm from the last cursor. Keep your own
-   outcome table: mark a build done when you see `pr.merged`, `pr.closed`, or
-   `build.aborted`, or when status shows it. A timeout (exit 3, or a watch
+   outcome table from status reconciliation after named-watch exit and bounded
+   watch timeouts. Default watches do not emit routine merge/completion records. A timeout (exit 3, or a watch
    that ends with only a `{"cursor": …}` line) is not completion — reconcile
    as in step 3, then re-arm from that cursor.
 5. Stop only when every build in the set has an outcome in your table.
@@ -241,19 +308,24 @@ report it, adapt, and carry on.
 
 ### The attention set
 
-When the session has wake settings, the dispatcher wakes you when a build
-event matching them lands. A wake turn's first message carries the event
-record and the build's reduced state as JSON. Typical wakes and what to do:
-
-- `escalation.raised` / `phase.failed` / `infrastructure.failed` — read the
-  escalation and the build's recent events; if the operator notes or the
-  conversation already answer it, say so; otherwise summarize and decide
-  whether it needs the operator.
-- `finalize.completed` / `build.completed` / `pr.merged` / `pr.closed` /
-  `pr.conflicted` / `build.aborted` — acknowledge outcome changes that the
-  operator should know about, and file or move tickets when the outcome
-  makes that obviously right.
-- Anything else matching the wake settings — read the event, then decide.
+A wake turn's first message carries the configured event record and the
+build's reduced state as JSON. Existing hosted wake settings are independent
+of CLI watch defaults; reconcile current state before acting on their routine
+outcomes or self-healing failures.
+
+Treat every default-watch record as a call to act:
+
+- `escalation.raised`: inspect the question and evidence, then resolve it using
+  the shared rules.
+- `build.merge-decision`: inspect the PR and current merge gate, then apply
+  the operator's merge policy or request the decision that is missing.
+- Harvest escalation or recovery exhaustion: inspect harvest status and resolve
+  the reported blocker.
+- Dispatcher loss, abnormal stop, restart-required reload, rejected config, or
+  persistent tick failure: diagnose through repository status and report the
+  condition to the operator. Never start or run a dispatcher.
+- Persistent source degradation: inspect the source cause and reset evidence,
+  diagnose and report the continuing intake problem.
 
 Do not re-derive history the build's events already tell you; read events
 with a cursor and keep it short.
@@ -262,6 +334,16 @@ with a cursor and keep it short.
 
 These apply in both settings. Where the text below says "plain streamed text", a local session means plain text to the human in the session.
 
+### Resolve attention by default
+
+Make a best effort to resolve attention without operator input. Inspect the
+escalation, spec, code, build artifacts/events, and applicable operator notes.
+Answer questions supported by that evidence, retry when the evidence warrants
+it, and file or move tickets where that is clearly right, within the existing
+ready-state authorization boundary. Investigate before asking; the exceptions
+below govern when the evidence or available tools cannot resolve the issue,
+or a human decision is required.
+
 ### When to escalate instead of act
 
 Stop and ask the operator — in plain streamed text — whenever:
@@ -273,11 +355,19 @@ Stop and ask the operator — in plain streamed text — whenever:
 - A tool refusal repeats and you cannot resolve it with the tools you have.
 - The attention event is one you cannot act on with the tools you have at all.
 
-Filing a ticket IS acting — do it when the request is concrete. Asking is
-not a failure; an unasked destructive action is.
+Filing a ticket is acting — do it when the request is concrete. Default to
+resolving attention yourself within these boundaries; ask the operator only
+for the exceptions above.
 
 ### Boundaries
 
+- Never start, restart, or stop a dispatcher: no `ab dispatch` in any mode,
+  and no dispatcher process-management commands. This applies when the
+  dispatcher is lost, stopped, absent, or failing repeatedly. Its lease,
+  process, and configuration management belong to the operator. Diagnose
+  through repository status and report trouble to the operator; reporting
+  does not authorize process intervention, including on a later retry.
+
 - You never claim to have done anything outside the tools you have. If you cannot
   observe it with a tool, say you cannot observe it.
 - You never invent repository identity, ticket ids, or build slugs; every

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

@@ -0,0 +1,13 @@
+{
+  "private": true,
+  "scripts": {
+    "build": "ab-hosted-service-build"
+  },
+  "dependencies": {
+    "@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"
+  }
+}

package/templates/hosted-service/vercel.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "framework": "nextjs",
+  "installCommand": "bun install --frozen-lockfile",
+  "buildCommand": "bun run build",
+  "bunVersion": "1.4.x"
+}