@defrex/autobuild 0.8.0

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

@@ -0,0 +1,79 @@
+# Hosted ticket protocol
+
+The hosted ticket protocol exposes the complete `TicketSource` port without
+exposing backend credentials. It shares the Autobuild and remote protocol
+version headers with the remote BuildStore. Both must exactly match the service;
+this release uses remote protocol version `2`.
+
+## Authentication and context
+
+Every request is `POST /tickets/<operation>`, has `Content-Type:
+application/json`, and requires `Authorization: Bearer <token>`. Only a signed,
+unexpired **deployment operator** token (`{ "operator": true, … }`) is accepted.
+Attributed human-operator, legacy admin, build, repository, and session tokens
+remain valid for their own routes but are denied on `/tickets`. Mint a deployment
+operator token offline with:
+
+```sh
+AB_STORE_SECRET='…' ab-hosted-store mint operator --ttl-seconds 3600
+```
+
+The strict request envelope is:
+
+```json
+{
+  "context": {
+    "teamKey": "ENG",
+    "claimedState": "Doing",
+    "createState": "Triage"
+  },
+  "input": {}
+}
+```
+
+`teamKey` is required. The state overrides are optional. They come from the
+requesting repository's `[tickets]` configuration and are applied only to that
+request; the service does not cache a team-bound adapter. `list-ready` also
+receives that repository's exact ready state and label criteria in `input`.
+Backend credentials, including `LINEAR_API_KEY`, are service environment only
+and never occur in this envelope or any response.
+
+## Operations
+
+The operation names and `input` values are:
+
+| Operation | Input | Successful response |
+|---|---|---|
+| `list-ready` | `{labels?: string[], state?: string}` | `TicketListing` |
+| `get` | `{id}` | `Ticket \| null` |
+| `claim` | `{id}` | `{claimed: boolean}` |
+| `comment` | `{id, body}` | `{ok: true}` |
+| `transition` | `{id, state}` | `{ok: true}` |
+| `create` | `{draft, options?}` | `Ticket` |
+| `update` | `{id, patch}` | `{ok: true}` |
+| `add-blocker` | `{id, blockerId}` | `{ok: true}` |
+| `remove-blocker` | `{id, blockerId}` | `{ok: true}` |
+| `dependency-states` | `{ids}` | `DependencyState[]` in input order |
+
+Requests and responses reject unknown fields. Tickets include `ref`, optional
+`creationKey`, `title`, `body`, optional `state`, `labels`, and optional
+`blockedBy`. The client projects every returned `ref.source` as `hosted` while
+preserving backend ids, URLs, titles, lifecycle values, labels, creation keys,
+and blockers.
+
+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.
+
+## Errors and conformance
+
+Errors are JSON `{ "error": string, "kind": "validation" | "not-found" |
+"auth" | "conflict" | "internal" }`. Authentication runs before body parsing
+or backend construction. Responses never include exception causes, stacks,
+environment values, or credentials. Client 401/403 responses become
+`AuthError`; other backend messages remain actionable.
+
+The shared `TicketSource` contract is normative for the database adapter and
+the hosted client/server pair. External pass-through is tested with a fake
+source behind HTTP. The existing opt-in live Linear contract remains the proof
+of Linear's GraphQL behavior; the hosted service uses that adapter unchanged.

package/skills/guide/references/setup.md

@@ -0,0 +1,289 @@
+# Repository setup
+
+Configure Autobuild outside the build pipeline. This conversation is not a
+build or phase. Work directly in the repository and involve the maintainer in
+choices that cannot be derived from source. Secrets belong in the environment
+or an ignored `.env`, never in `autobuild.toml`, commits, or validation reports.
+
+## Choose the execution environment
+
+Keep the default `git-worktree` provider unless the maintainer explicitly opts
+into remote builds. It creates local disposable worktrees and uses the tools,
+network, and credentials available to the dispatcher machine.
+
+For remote execution, set `[workspace].provider = "vercel-sandbox"`. A Vercel
+Sandbox is a fresh independent machine; a runtime that works on the setup
+machine is not evidence that it works there. Confirm all of these with the
+maintainer before selecting it:
+
+- the intended Vercel team and project;
+- durable dispatcher authentication with `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and
+  `VERCEL_PROJECT_ID`, or short-lived `VERCEL_OIDC_TOKEN` obtained from a linked
+  project (`vercel link` and `vercel env pull`); when validating a target other
+  than the current directory, export OIDC in the launcher environment because
+  the Vercel SDK resolves it from ambient process state. Access-token
+  credentials in the target's ignored `.env` are the durable choice for a
+  continuously running local dispatcher;
+- an HTTPS `github.com/owner/repository` origin and `forge = "github"`;
+- a dispatcher-side push-capable `GITHUB_TOKEN` or `GH_TOKEN`;
+- for a private repository, a separate read-only clone identity named by
+  `gitUsernameEnv` and `gitPasswordEnv`;
+- an HTTPS hosted `AB_STORE` reachable from Vercel and a scoped `AB_TOKEN`;
+- each selected role and alternate's runtime/model, its pinned
+  `[workspace.config.runtimeProvisioning.<runtime>]` commands, and the API
+  credential names it needs in `[workspace.config].environmentVariables`.
+
+Do not put `AB_STORE`, `AB_TOKEN`, Vercel credentials, Forge credentials, or
+private-clone credentials in `environmentVariables`. Autobuild supplies Store
+credentials separately, keeps clone credentials out of guest commands, and
+performs publication from the trusted host.
+
+```toml
+[workspace]
+provider = "vercel-sandbox"
+
+[workspace.config]
+image = "vercel/sandbox/universal:latest"
+vcpus = 4
+timeoutSeconds = 2700
+environmentVariables = ["AI_GATEWAY_API_KEY"]
+# Ordered system-level steps run once in every fresh/replacement sandbox as root.
+provisioning = [
+  { name = "system-install", command = """apt-get update
+DEBIAN_FRONTEND=noninteractive apt-get install -y chromium""" },
+  { name = "browser-smoke", command = "CHROMIUM_BIN=/usr/bin/chromium ./scripts/browser-smoke.sh" },
+]
+# Private repositories only:
+# gitUsernameEnv = "AB_GIT_READ_USER"
+# gitPasswordEnv = "AB_GIT_READ_TOKEN"
+
+[workspace.config.runtimeProvisioning.pi]
+install = "npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.84.4"
+preflight = "test \"$(pi --version)\" = \"0.84.4\""
+```
+
+Use a `vercel-ai-gateway/...` Pi model with `AI_GATEWAY_API_KEY` in the
+dispatcher environment. Do not copy `~/.pi`, OAuth refresh tokens, or any local
+runtime auth state, and do not attempt interactive login in a sandbox. Runtime
+names are open: a plugin runtime uses the same strict map, for example
+`[workspace.config.runtimeProvisioning.opencode]`, with its own immutable
+install and exact-version preflight commands.
+
+## Make the environment reproducible
+
+Inspect the repository's manifests, documentation, CI, test layout, and
+conventions. Read the installed sibling `../SKILL.md` for Autobuild's complete
+configuration and ticket surfaces.
+
+Use the supported `vercel/sandbox/universal` image. Other managed images and
+custom VCR images are rejected. Autobuild remains stack-neutral. For Vercel,
+put repository-specific operating-system packages and machine-level tooling in
+the ordered `[workspace.config].provisioning` list. Each strict `{ name,
+command }` entry runs from the checkout through `sh -c` with provider root
+authority after pinned Bun is verified and before dependency bootstrap,
+`[commands].setup`, or an agent. It runs once per fresh environment and repeats
+on every replacement. Commands are declarative TOML string data, not evaluated
+configuration logic. Local git worktrees never run this list; ensure their host
+already has required system tooling.
+
+Put each selected runtime's immutable install and executable/version check in
+its `runtimeProvisioning` entry. Autobuild runs install then preflight after
+checkout dependencies in every fresh/replacement sandbox and before the
+readiness probe, writes the marker only after success, and reruns every
+preflight before each build runner. A failure names the runtime, selecting
+role/alternate, and field and starts no agent. Runtime provisioning receives
+only the API credentials named by `[workspace.config].environmentVariables`.
+
+Keep package-level and checkout-level bootstrap in an idempotent
+`[commands].setup`. It runs after system provisioning and must remain safe to
+rerun on attachment. Do not repeatedly install OS packages there. Expose only
+required runtime credentials through
+`[workspace.config].environmentVariables`, keep generated caches disposable,
+and lock dependencies in the repository. A browser-capable repository should
+check in a dependency-free `scripts/browser-smoke.sh` that starts its dev server,
+uses a repository-controlled path such as `CHROMIUM_BIN=/usr/bin/chromium` to
+launch headless Chromium in the same guest, verifies the rendered page, and
+exits nonzero on failure. Then:
+
+1. Configure real `[commands]` and ordered `[verify]` steps from the toolchain
+   this repository actually uses. Do not invent commands or retain placeholders.
+2. Decide the runtime and model arrangement for every pipeline role and
+   alternate. The runtime that launched setup and the temporary fresh-skeleton
+   default do not constrain the final arrangement.
+3. Choose the ticket source and workflow states. Confirm account/team facts and
+   required environment credentials. Configure end-to-end verification with the
+   repository's real lifecycle and tools. When judgment is required, author a repository-owned
+   agent-verify skill and select it from an agent verify step.
+4. Preserve an existing `autobuild.toml` and unrelated repository choices on a
+   rerun. Change only choices the maintainer approves.
+5. Commit the config, setup files, lockfiles, and installed reference changes,
+   then push them to `baseBranch`. A remote sandbox clones the authoritative
+   GitHub revision; it cannot acquire local-only edits.
+6. Run `ab init --validate`. Fix every named failure and rerun until every check
+   passes. Only then use the installed grooming/ticket skills to create the
+   first groomed Ready ticket and start `ab dispatch`.
+
+Validation is explicit and noninteractive. It does not dispatch, claim a
+ticket, or create build, phase, session, event, transcript, or artifact history.
+For local execution it identifies and removes a disposable detached worktree.
+For Vercel it identifies and permanently deletes a fresh unnamed sandbox, even
+when system or runtime provisioning, setup, or a probe fails; cleanup failures
+name the environment for manual deletion. Its `system provisioning` check lists
+completed step names (or says none were declared) before guest setup checks. A
+failed step reports its name, command, status, labeled stdout/stderr, and
+remediation without marking the environment ready. It provisions/preflights
+every effective primary and alternate runtime, then runs `commands.setup`, loads
+repository plugins, and checks every
+selected primary/alternate runtime and model, and performs a read-only Store
+request in the candidate execution context. If the local database is absent,
+validation reports that no repository history is available without creating
+`.autobuild` or any SQLite files. If it exists, validation copies the database
+and any WAL/SHM sidecars to a disposable filesystem snapshot and inspects that
+copy without SQLite-opening or modifying the repository Store files. It never
+silently falls back from Vercel to local execution. Local launcher probes
+printed by ordinary `ab init` are only setup-agent discovery and are not remote
+readiness evidence.
+
+Typical remediation is intentionally specific: add a missing system executable
+to `workspace.config.provisioning` (or a package dependency to setup) while
+retaining the universal image; add a runtime credential name to
+`environmentVariables` and its value to the dispatcher environment; correct the
+Vercel team/project credential set; provide separate private-clone credentials;
+use an HTTPS GitHub origin and hosted Store; authorize the Store token; or commit
+and push the selected base branch.
+
+## Repository identity is the origin, not a checkout path
+
+Repository identity in the Store, dispatcher, `ab builds`, `ab build status`,
+`ab repository status`, and the web app is the repository's **normalized origin
+URL** (`https://github.com/owner/repository`), not a checkout's absolute path.
+Two checkouts of the same repository — on different hosts, or a dispatcher and
+its sandboxes — agree on one identity.
+
+Records written before this change are keyed by checkout path and are **not
+migrated**. They remain visible only where their recorded `repoOrigin` matches
+the querying checkout's origin; dropping the old identity's history is an
+accepted trade for path-free operation.
+
+## Running the dispatcher without a checkout (origin mode)
+
+A dispatcher can operate a repository with no local checkout at all — from a
+serverless function or any host with only network access:
+
+```sh
+ab dispatch --repository https://github.com/owner/repository \\
+  --plain --store https://hosted-store.example \\
+  # environment: AB_TOKEN (store), GITHUB_TOKEN or GH_TOKEN (GitHub API)
+```
+
+`--repository` (or `AB_REPOSITORY`) is the normalized origin. Origin mode
+requires an HTTPS `AB_STORE` plus `AB_TOKEN`, an exported `GITHUB_TOKEN` or
+`GH_TOKEN`, and `forge = "github"`; the interactive dashboard is unavailable
+(`--plain` or no TTY). Origin mode never consults the gh CLI: a checkout-less
+host has no gh and no keyring, and the only workspace provider it can run,
+`vercel-sandbox`, injects that same exported token for publication. The gh CLI
+fallback (`GITHUB_TOKEN`, then `GH_TOKEN`, then the login stored by `gh auth
+login`) is a checkout-mode convenience for a local dispatcher whose workspace
+provider is not `vercel-sandbox`; that provider requires the exported token in
+every mode. The
+startup configuration — and every per-tick reload — is `autobuild.toml` read
+from the forge at the current `baseBranch` (the first read resolves against the
+repository's default branch), so a push to the base branch is honored by a
+later tick without restarting anything. Configs declaring local `plugins` are
+rejected: plugin code is checkout-relative. The guest installs the Autobuild
+distribution published for its version — the npm registry tarball, else the
+GitHub release asset `autobuild-<version>.tgz` — so origin-mode dispatch
+requires a published release.
+
+### Guest distribution version selection and delivery
+
+The guest's distribution version is selected by the archive source, and both
+sources agree with the running system by construction:
+
+- **Source checkout** (dispatcher running from a repository checkout): the
+  guest archive is packed from the host tree with `bun pm pack`, so the guest
+  runs the dispatcher's own code.
+- **Origin mode** (checkout-less dispatcher): the guest archive is the release
+  asset `autobuild-<version>.tgz` fetched from the canonical repository at the
+  **running dispatcher's version** (read from the deployed distribution's
+  `package.json`), so the guest runs the dispatcher's own release.
+
+The hosted remote store enforces exact **version lockstep**: every client
+request must carry an `x-autobuild-version` equal to the server's, and any
+mismatch — a guest older *or* newer than the store — is rejected with a 409
+`remote store version mismatch`. Guest, store, and dispatcher versions
+therefore cannot be mixed: a distribution fix reaches guests only after
+`tools/release.ts` cuts a release (credential-gated; requires GitHub
+credentials — a documented delivery dependency, not an automatic propagation)
+**and** the hosted store and dispatcher are upgraded to that release in the
+same lockstep window. If the release is cut but the store upgrade lags, guests
+carrying the new distribution fail loudly against the old store (409) rather
+than running silently stale.
+
+Provisioning records the installed distribution's version in the guest's
+`/opt/autobuild/.distribution-version` marker. A reused persistent sandbox
+whose marker disagrees with the version the current system would deliver —
+which includes every guest provisioned before the marker existed — is
+refreshed in place (archive re-fetched, extracted, and production-installed)
+before being reused, so an upgraded dispatcher retrofits its existing guests
+instead of resuming a stale distribution. A refresh failure deletes the
+sandbox so the next provisioning pass rematerializes it from scratch.
+
+After a lockstep upgrade, confirm a fix-bearing guest from the guest
+perspective:
+
+1. `ab build status <slug> --json` with the ambient build identity for a
+   build whose record carries `repoOrigin` succeeds and exposes `.pr.number`
+   and `.pr.url` even though the guest's checkout path differs from the path
+   recorded at build creation (post-#297 origin-equality behavior).
+2. The same command for a genuinely foreign repository's slug still fails
+   with the `belongs to repository … not …` rejection.
+
+Local `git-worktree` dispatch keeps working from a checkout exactly as before;
+apart from the identity change, `ab dispatch` behaves as it did.
+
+## Hosted deployment variables
+
+A hosted-store deployment configures its web/auth variables once — see the
+hosted service README and the complete environment reference in the pinned
+distribution checkout: `BETTER_AUTH_URL`, `AB_WEB_ALLOWED_EMAILS`,
+`AB_WEB_REPOSITORIES`, and the optional `AB_WEB_MCP_RESOURCE` — the protected
+resource the hosted MCP server (docs/mcp.md) binds its OAuth tokens to,
+defaulting to `<BETTER_AUTH_URL>/mcp`. Set it only when a proxy or custom
+domain fronts the deployment under a different public URL than
+`BETTER_AUTH_URL`; the value must be an absolute http(s) URL (https in
+production) or every MCP client's discovery binds tokens to the wrong
+resource.
+
+## Authoring an agent verifier
+
+A repository-owned agent-verify skill is a verifier, not a reviewer: it drives
+the running application and observes whether the spec's acceptance criteria
+hold. It does not inspect the diff for style or edit product code.
+
+Its session instructions must preserve this contract:
+
+1. Run `ab context`. The verifier receives `.ab/spec.md`, the configured step,
+   the commit range, and, after escalation is answered, `.ab/guidance.json`.
+2. Exercise each applicable acceptance criterion through the repository's real
+   application lifecycle. Prefer the narrowest honest flow that catches a
+   regression.
+3. Write criterion-oriented evidence: criterion, action, observation, and
+   pass/fail. Failures include reproduction inputs, expected/observed behavior,
+   and relevant repository-native logs.
+4. Deposit passing review evidence explicitly with
+   `ab artifact put <kind> <file> --attach`. Never attach failed or partial
+   output; use stable kinds so retries replace the designation.
+5. Finish with exactly one terminal:
+
+   ```text
+   ab verdict pass --notes <report-file>
+   ab verdict fail --report <report-file>
+   ab verdict skip --reason "Why this entire step does not apply"
+   ```
+
+An applicable behavior that cannot be exercised is a failure with an
+explanation, never a skip or silent pass. Use `skip` only when the complete step
+does not apply. If guidance still cannot make a verdict possible, escalate and
+explain what remains unresolved. Record out-of-scope work with `ab observe`;
+the verifier does not fix it.

package/skills/guide/references/spec-standard.md

@@ -0,0 +1,63 @@
+# The spec standard
+
+This document is the complete reference definition of **buildable**. Every
+ticket-producing surface uses the same standard: interactive specification,
+harvest, ingesters, and dispatch. An ingester's proposal is a spec written to
+this standard with weaker evidence. Dispatch's quality gate returns any Ready
+ticket that cannot be expanded into a conforming spec to Triage, citing this
+standard.
+
+A conforming spec has four parts:
+
+## 1. What and why — never how
+
+State the change in terms of observable behavior and the reason it matters.
+Implementation strategy belongs to the `plan` phase; a spec that prescribes
+file names, function signatures, or libraries is over-specified and will
+mislead the planner. One or two paragraphs.
+
+- Bad: "Add a `RateLimiter` class in `src/middleware/` using a token bucket."
+- Good: "Login attempts are currently unlimited; an attacker can brute-force
+  credentials. After this change, repeated failed logins from one source are
+  throttled, and legitimate users see a clear retry-after message."
+
+## 2. Acceptance criteria
+
+A checklist of verifiable statements that define done. Each criterion must be
+something a reviewer or a verify step can actually check — behavior, not
+intention. These become the contract that `plan-review`, `code-review`, and
+`verify:*` all measure against.
+
+- Each criterion is a single observable fact ("a sixth failed login within
+  five minutes returns 429 with a Retry-After header").
+- Avoid criteria that cannot fail ("code is clean").
+- Do not predict which repository paths implementation will touch. Tickets
+  describe observable behavior; any repository-configured path applicability
+  is evaluated later by the kernel from the build's actual diff in each verify
+  cycle.
+
+## 3. Out of scope — explicit
+
+Name the adjacent work this spec deliberately excludes. This is what keeps
+builds from thrashing: the implementer files an `ab observe` observation for
+out-of-scope discoveries instead of expanding the diff, and the reviewer
+cannot demand out-of-scope work in findings.
+
+## 4. Evidence
+
+Links and data supporting the why: the Sentry issue and its frequency, the
+observation events that were clustered into this proposal, the conversation
+where the human decided this matters. Evidence strength varies by origin —
+a human-authored `/spec` may cite a decision; an `ingest:sentry` proposal
+cites error counts and affected users. Weak evidence is acceptable; absent
+evidence is not.
+
+---
+
+## Immutability during a build
+
+The spec is the build's contract artifact (kind `spec`, revision 0). It
+cannot change during a build because every downstream reviewer approves
+conformance *to it*. A phase that discovers the spec itself is wrong raises
+an escalation (`ab escalate`); a human answers, the spec gets revision N+1,
+and the build restarts from `plan`.

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

@@ -0,0 +1,59 @@
+# Filing tickets with blockers safely
+
+`ab ticket create --blocked-by` validates prerequisite ids and records blocking
+relationships, but a single CLI command is **not an atomic publication guarantee**.
+In particular, direct Linear and hosted Linear create the issue first and add
+its blocker relationships in separate requests. If the issue is already in the
+ready state, a dispatcher can see it before those relationships exist. A
+successful create response containing every blocker does not prove that no build
+was claimed during the request. Harvest's durable creation reservations protect
+its own filing workflow; ordinary interactive ticket creation has no such hold.
+
+## Safe interactive workflow
+
+For tickets with prerequisites, determine the intended final state from the
+human's instruction, then the configured create state or source default. Do not
+invent a different final destination. If that destination is ready, or the source
+default's eligibility is unknown, stage the ticket in a known non-ready state
+before publishing it. Use the repository's triage state when it differs from its
+ready state. This temporary staging does not require another placement approval.
+If no non-ready state can be established, resolve that before creating the
+dependent; never guess that a name such as "Backlog" is safe in every repository.
+
+1. Create prerequisites in dependency order and extract each new `.ref.id` from
+   the complete `--json` response, never the human confirmation line.
+2. Create the dependent in the non-ready staging state with **all** known
+   `--blocked-by` ids in the create command.
+3. Read it back with `ab ticket show <id> --json`. Verify its state is still
+   non-ready and every expected blocker is present. Repair missing relationships
+   through `ab ticket block`, then read back again.
+4. Only after verification, move it to the intended final state with
+   `ab ticket move <id> <state> --json`. Verify the final state and blockers.
+
+For a repository whose configured triage and ready states are `Triage` and
+`Ready`, respectively, and whose human requested ready placement:
+
+```sh
+ab ticket create "Dependent" --body dependent.md --state Triage --blocked-by ENG-8,ENG-9 --json > dependent-ticket.json
+dependent_id="$(jq -r '.ref.id' dependent-ticket.json)"
+ab ticket show "$dependent_id" --json
+# Verify state and the full blocker set before the following command.
+ab ticket move "$dependent_id" Ready --json
+```
+
+If creation fails after an issue may have been written, find and repair that
+issue rather than blindly creating a duplicate. Leave partial work non-ready
+until the blockers are verified. If the intended destination was already
+non-ready, create there, verify, and leave it there. For a source default that
+cannot be determined, clarify the final destination rather than silently making
+the ticket ready.
+
+## Already-claimed work
+
+Adding blockers does not stop a build already claimed from an earlier listing.
+When the human authorizes restarting premature work: request `ab abort <slug>`,
+wait for dispatcher cleanup to finish and return the ticket to triage, verify
+or repair the blocker set, and only then move the ticket back to ready. Moving
+the ticket before cleanup finishes can be overwritten by cleanup. Ready with
+unresolved blockers is the normal waiting state: dispatch rechecks dependencies
+and claims the ticket only after they resolve and other readiness gates pass.

package/skills/harvest/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: harvest
+description: Synthesize a claimed observation snapshot into structured, spec-standard ticket proposals. Invoked only by the harvest runner.
+---
+
+# /ab-harvest <run>
+
+You are the harvest producer. The repository runner has already scanned and
+claimed a fixed set of structured `observation.recorded` occurrences. You
+cluster and author; you never create or move tickets.
+
+1. Run `ab harvest context`. Read `.ab/observations.json`,
+   `.ab/originating-tickets.json`, and `.ab/ledger.json`. The originating-ticket
+   context shows scan-time source match, existence, and resolution state; filing
+   refreshes matching refs before create. On a revise round, address every item
+   in `.ab/findings.json` and revise the prior `.ab/proposals.json`.
+2. Write `.ab/proposals.json` with this exact top-level shape:
+
+   ```json
+   {
+     "proposals": [
+       {
+         "action": "create",
+         "title": "...",
+         "whatWhy": "...",
+         "acceptanceCriteria": ["..."],
+         "outOfScope": ["..."],
+         "blockedBy": ["SOURCE-123"],
+         "observations": [{"build": "slug", "seq": 12}]
+       }
+     ]
+   }
+   ```
+
+   Every claimed `{build, seq}` must appear exactly once. Cluster occurrences
+   only when they describe the same underlying problem. A `create` must be a
+   useful spec: what/why rather than implementation, verifiable criteria, and
+   explicit scope exclusions. `blockedBy` is optional. Filing automatically
+   blocks a create on every unresolved, same-source originating ticket of its
+   clustered observations, using fresh lifecycle state; do not restate that
+   automatic dependency in `blockedBy` to make it take effect. When evidence
+   establishes some other ticket as a hard prerequisite, include that ticket's
+   source-local id in `blockedBy` as well as explaining it in the spec.
+   Contextual citations, related work, and nonbinding sequencing preferences
+   such as “do this later” are not blockers. Never invent an id or turn every
+   ticket mention into a dependency.
+
+   You may instead use a known prior proposal from `.ab/ledger.json`:
+
+   ```json
+   {"action":"join","ticket":{"source":"...","id":"..."},"reason":"...","observations":[...]}
+   {"action":"suppress","reason":"...","observations":[...]}
+   ```
+
+   Join only an existing unresolved ticket supplied by the ledger. Suppress a
+   duplicate whose ledger ticket is resolved/missing, or a record that cannot
+   support actionable work. Never invent a ticket reference.
+3. Finish exactly once:
+
+   ```sh
+   ab harvest submit .ab/proposals.json
+   ```
+
+Do not call the TicketSource, edit tracker files, dispatch a build, push, or
+infer state from your own stdout. If evidence is weak, preserve that limitation
+in acceptance criteria rather than inventing facts.

package/skills/harvest-review/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: harvest-review
+description: Fresh adversarial review of one harvest proposal set. Invoked only by the harvest runner.
+---
+
+# /ab-harvest-review <run>
+
+You are the fresh skeptic in the observation-harvest convergence loop. You do
+not author proposals or touch tickets.
+
+1. Run `ab harvest context`.
+2. Review `.ab/proposals.json` against `.ab/observations.json`,
+   `.ab/originating-tickets.json`, `.ab/ledger.json`, and every prior
+   `history/findings-r*.json` file. Origin lifecycle is scan-time context;
+   deterministic filing refreshes matching refs before create.
+3. Check all of the following:
+   - every claimed `{build, seq}` occurs exactly once;
+   - clusters describe one underlying problem rather than superficial keyword
+     overlap;
+   - create proposals meet the spec standard (what/why, verifiable acceptance
+     criteria, explicit out-of-scope, evidence-supported claims);
+   - filing automatically blocks a create on unresolved, same-source
+     originating tickets for its clustered observations; neither producer nor
+     reviewer must restate that originating dependency in `blockedBy` for it to
+     take effect;
+   - evidence-supported prose saying some other ticket must complete before work
+     can start has the same source-local id in `blockedBy`; a prose-only hard
+     prerequisite is not approvable;
+   - every `blockedBy` id is justified by evidence as a hard start gate;
+     contextual citations, related work, and nonbinding preferences such as
+     “do this later” must not become blockers, and ticket ids are never invented;
+   - joins name only an unresolved ledger proposal and resolved/missing ledger
+     tickets are tombstones, not recreated work;
+   - suppression has a concrete evidence-backed reason;
+   - no proposal asks harvest to groom, ready, claim, or dispatch anything.
+4. Write review notes to `.ab/harvest-review.md`, then finish exactly once:
+
+   ```sh
+   ab harvest verdict approve --notes .ab/harvest-review.md
+   ab harvest verdict revise --notes .ab/harvest-review.md --findings .ab/findings.json
+   ab harvest verdict escalate --notes .ab/harvest-review.md --reason "the human question"
+   ```
+
+Use `escalate` only when evidence or product intent requires human judgment,
+not as a substitute for a precise revision finding.
+
+## Writing findings
+
+For `revise`, `.ab/findings.json` is an array of the normal finding drafts:
+`severity`, `summary`, optional `detail`, and `persists` containing ids from
+prior harvest review rounds. The work under review is this round's proposal
+set.
+
+`persists` means the defect a prior finding named is still present in the
+work under review — not that a new problem falls in the same category as
+one already fixed. Test it that way: if the exact defect the prior finding
+named is gone, the chain ends there, however closely your new finding
+resembles it. A new instance of a defect class whose reported instance was
+fixed is fresh work and starts its own chain — raise it with no `persists`
+link. Mark honestly in both directions: neither re-litigate a resolved
+finding nor let a dodged one look fresh, because the kernel mechanically
+escalates a chain that persists too long, and a stalemate is the only
+thing that counter can usefully measure.