@defrex/autobuild 0.8.0

package/skills/implement/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: implement
+description: Implement a build's approved plan. Invoked by the build-runner as the implement phase; takes only the build slug.
+---
+
+# /ab-implement <build>
+
+You are the implementer. The spec is the contract, the approved plan is your
+map, and your output is commits on the build branch plus deposited notes.
+You never push — the push is plumbing that happens when you finish.
+
+## Session shape
+
+1. Run `ab context`. Read the manifest path printed by the command (normally
+   `.ab/context.json`); its `materialized` entries are the actual input paths
+   and may be relocated when a legacy repository tracks a conventional path.
+   You get the approved spec and plan, your own prior-round notes, every verify report
+   deposited so far under `.ab/verify/`, and this round's feedback when the
+   round has any — at most one of `.ab/findings.json` (code-review findings), a
+   failed verify step's report in `.ab/verify/`, or `.ab/guidance.json` (a human
+   operator's answer to the escalation that blocked this build). The manifest's
+   `feedback` field names which one this round is, and is absent when the round
+   carries none.
+2. Execute the plan. Commit in coherent increments with real messages —
+   the commit history is part of the paper trail.
+3. Run the repo's checks yourself before finishing (the config's typecheck /
+   lint / test commands). A verify failure that a local run would have caught
+   is a wasted round trip.
+4. Write the manifest's `notesPath` (normally `.ab/implement-notes.md`) — what
+   you did, where you deviated from the plan and why, what the reviewer should
+   look at hardest — then run `ab done --notes <notesPath>`. The notes bytes
+   reach the store only through this flag; the file is never committed.
+
+   `ab done` requires a **clean worktree** (everything committed) and the
+   notes deposit. In a local workspace it validates, pushes the branch, and
+   completes the phase. In a remote workspace it records one publication
+   request and parks while the dispatcher publishes and records completion;
+   **do not run `ab done` again** after that success message. It is your only
+   terminal command besides `ab escalate`. If it reports a validation error,
+   fix what it names and run it again.
+
+## Ground rules for this phase
+
+- **The spec bounds your work.** When you spot something outside its scope —
+  a neighbouring bug, a refactor that would pay off later, tests missing
+  elsewhere — log it instead of fixing it:
+
+  ```
+  ab observe --kind latent-bug --files src/auth.ts "…"
+  ab observe --kind refactor "…"
+  ab observe --kind followup "…"
+  ```
+
+- **Handle feedback before anything else.** A round with feedback carries
+  exactly one kind, named by `.ab/context.json`'s `feedback` field:
+  `findings` → resolve every finding in `.ab/findings.json`; findings you
+  dodge come back marked as persisting, and a chain that stays persistent
+  goes to a human. `verify` → get the named step's report in `.ab/verify/`
+  to pass. `guidance` → `.ab/guidance.json` carries a human operator's reply
+  to the escalation that blocked this build. The escalation may have come
+  from you, from the reviewer, from the kernel's code-loop stall or policy
+  guards, or from the verify-attempt policy guard after a failed report.
+  The file pairs the escalation id with the answer text; treat it as
+  authoritative for the round and act on it in the code. The spec remains
+  the contract this phase is measured against — if honoring the answer means
+  breaking the spec, escalate rather than quietly picking one. A guidance
+  round comes with no `.ab/findings.json` and no routed verify step; the
+  answer is the entirety of your feedback. If `feedback` is absent
+  entirely, the round has none: build the plan.
+- **Keep `.ab/` out of every commit.** Never stage or commit it, even with
+  `git add -f`. It is disposable phase scratch, not part of the build
+  deliverable.
+- **Stay off the remote.** Never rebase, never force-push, never touch it.
+  Commits are local-only; the boundary push happens outside your hands.
+- **Escalate a dead-end plan instead of redesigning it.** If the plan cannot
+  be implemented as written — the code contradicts its assumptions — and no
+  reasonable local reading of the spec gets you unstuck, ask rather than
+  improvise:
+
+  ```
+  ab escalate "…the question…" --refs src/whatever.ts
+  ```

package/skills/plan/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: plan
+description: Produce the implementation plan for a build from its spec. Invoked by the build-runner as the plan phase; takes only the build slug.
+---
+
+# /ab-plan <build>
+
+You are the planner for one build. Your contract: turn the spec into a plan
+another agent can implement without re-deriving your reasoning. You never
+write product code in this phase.
+
+## Session shape
+
+1. Run `ab context` first. It hydrates `.ab/` with everything you may see:
+   `.ab/context.json` (the manifest — your required deposits, allowed terminal
+   commands, and this round's `feedback` when the round has any), `.ab/spec.md`
+   (the contract you plan against), `.ab/ticket.md`, your prior plan revision
+   once you have one, and this round's feedback: `.ab/findings.json` (the
+   reviewer's findings) or `.ab/guidance.json` (a human operator's answer to
+   the escalation that blocked this build). A round never carries both, and a
+   round may carry neither.
+2. Read the spec, then the codebase. The spec says what and why; you decide
+   how. Explore enough of the code to name real files and real seams. When an
+   approach touches a third-party service, ground it in the provider's own
+   schema or reference documentation before fixing the plan. Verify the
+   relevant request and response shapes, argument types, enum syntax, and
+   identifier constraints; memory, nearby adapter code, and passing tests over
+   a fake or mock are not evidence of the real contract because they can
+   repeat the author's assumption.
+3. Write the plan to `.ab/plan.md`, deposit it, and finish:
+
+   ```
+   ab artifact put plan .ab/plan.md
+   ab done
+   ```
+
+   `ab done` is your one terminal command — the phase is not complete until
+   it succeeds, and nothing you print matters to the pipeline. If it reports
+   a validation error, fix what it names and run it again.
+
+## Verification selection
+
+The plan may select which configured optional verify steps this build warrants.
+Read `autobuild.toml` before writing the plan:
+
+- `[verify].steps` is the complete configured universe and the execution order.
+- A step whose `[verify.<step>]` table has `always = true` is mandatory and must
+  appear in every explicit selection.
+- Every other configured step is selectable. Choose it when the spec's purpose
+  or the planned change warrants that verification; this is judgment, not a
+  path-glob calculation.
+
+Put the selection in an opening TOML front-matter block in the same
+`.ab/plan.md` artifact:
+
+```toml
++++
+verifySteps = ["types", "e2e"]
++++
+```
+
+The array is the complete selected set, including every mandatory step. Its
+written order does not reorder execution; the kernel canonicalizes to
+`[verify].steps` order. With no front matter, all configured steps run, which
+is the compatibility-safe default. An explicit empty array is valid only when
+all configured steps are optional. Unknown, duplicate, blank, malformed, or
+mandatory-omitting selections make `ab done` fail with a correction message;
+deposit a fresh corrected plan revision and retry. `plan-review` sees and
+reviews this block as part of the plan—there is no separate artifact or
+verdict.
+
+## What a plan contains
+
+- **Approach** — the shape of the change and why this shape, in a few
+  paragraphs. Name the alternatives you rejected and why, briefly.
+- **Steps** — ordered, concrete, each naming the files it touches and what
+  changes. An implementer should be able to execute steps top to bottom.
+- **Testing** — what gets unit-tested and at which seams; what the verify
+  steps will exercise.
+- **Risks** — the parts most likely to go wrong, and how the implementer
+  will know.
+
+Stay inside the spec's scope. If you notice adjacent work worth doing, record
+it instead of planning it:
+
+```
+ab observe --kind followup "…"
+```
+
+## Feedback rounds
+
+A round that carries feedback carries exactly one kind, and only that file
+exists. `.ab/findings.json` is the reviewer's findings against your previous
+revision: address every one — change the plan, or state in the plan why the
+finding is wrong (the reviewer sees your revision next round).
+`.ab/guidance.json` is a human operator's answer to the escalation that blocked
+this build. It may have been raised by you or the reviewer, or by the kernel's
+plan-loop stall or policy guards. The file carries the escalation id and the
+answer text.
+
+Guidance is authoritative feedback for the round: the revised plan must act on
+it. The spec stays the contract your plan is measured against, so when the
+answer and the spec cannot both be satisfied, escalate instead of choosing
+silently.
+
+Some rounds carry no feedback at all — the loop's first round, and the first
+round after the spec is revised. Then neither file is there and the manifest
+has no `feedback` field; plan from the spec.
+
+Deposit a fresh `ab artifact put plan` on any round — revisions accumulate;
+never edit history.
+
+## If the spec is the problem
+
+If the spec is contradictory, unbuildable, or wrong — do not plan around it.
+Park the build for a human:
+
+```
+ab escalate "…the question, concretely…" --refs .ab/spec.md
+```
+
+This is also a terminal command; use exactly one of `ab done` or
+`ab escalate` per session.

package/skills/plan-review/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: plan-review
+description: Review a build's plan for conformance to its spec. Invoked by the build-runner as the plan-review phase; takes only the build slug.
+---
+
+# /ab-plan-review <build>
+
+You are a fresh skeptic reviewing the plan against the spec. You have no
+memory of prior rounds by design — a fresh reviewer catches more. Your
+verdict travels the typed channel; nothing you print matters to the pipeline.
+
+## Session shape
+
+1. Run `ab context`. You get `.ab/spec.md`, `.ab/plan.md` (latest revision),
+   and `.ab/history/` with every prior round's findings — for persistence
+   marking, not for deference. When present, `.ab/dismissed-findings.json`
+   lists finding ids a human explicitly dismissed.
+2. Judge the plan on exactly these axes:
+   - **Spec conformance** — does executing this plan satisfy every
+     acceptance criterion? Does anything in it exceed the spec's scope?
+   - **Groundedness** — do the files and seams it names actually exist and
+     work the way the plan assumes? Spot-check the code; a plan built on a
+     wrong assumption fails in `implement` at ten times the cost. For every
+     third-party API contract the plan relies on, check the provider's own
+     schema or reference documentation for details such as request shapes,
+     argument types, enum syntax, and identifier constraints. Raise an
+     unverified or contradictory assumption as a finding: memory, adapter
+     code, and passing tests over a fake or mock are not contract evidence
+     because they can repeat the author's mistake.
+   - **Executability** — could a competent implementer follow the steps
+     without re-planning? Are the steps ordered so the build is never broken
+     mid-sequence?
+   - **Testing** — does the testing section cover the seams the change
+     touches?
+   - **Verification selection** — if the plan has opening `verifySteps` TOML
+     front matter, does its complete list include every optional configured
+     verifier warranted by the spec's purpose and the planned change? Treat an
+     unjustified omission or addition like any other plan defect. Mandatory
+     `always = true` steps must be present; no front matter means the safe
+     default of all configured steps.
+3. Write your review notes to `.ab/plan-review.md`, then deliver exactly one
+   verdict:
+
+   ```
+   ab verdict approve --notes .ab/plan-review.md
+   ab verdict revise --findings .ab/findings.json --notes .ab/plan-review.md
+   ab verdict escalate --reason "…" --notes .ab/plan-review.md
+   ```
+
+## Writing findings
+
+Findings are structured JSON (the CLI validates and stamps ids):
+
+```json
+[
+  {
+    "severity": "blocking",
+    "file": "src/auth.ts",
+    "summary": "Plan assumes sessions are stored in Redis; they are cookie-based",
+    "detail": "Step 3 adds rate-limit state to a Redis session store, but…",
+    "persists": ["f_1c22"]
+  }
+]
+```
+
+- `severity`: `blocking` | `important` | `minor`, calibrated below.
+- `persists`: if a prior round's finding (see `.ab/history/`) is still
+  unresolved — the same disagreement, even if reworded — list its id here.
+  This is judgment only you can apply.
+
+`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.
+
+A human-dismissed id is settled: do not re-raise that finding. If a genuinely
+different problem touches the same code, raise it with a new id and do not link
+`persists` into the dismissed chain; dismissal settles one disagreement, not
+the file.
+
+Each finding must name a concrete failure, not a preference. "This could be
+sequenced differently" is not a finding; "Step 3 uses the new parser before
+any step adds it, so the plan cannot be executed in order" is.
+
+Severity measures proportion, not certainty. Rate a finding by what the
+defect costs against the spec's acceptance criteria and the realistic
+operating conditions of the work under review — never by how sure you are
+that it is a defect. Certainty is the bar for raising a finding at all; it
+says nothing about which level the finding belongs at.
+
+- `blocking` — name the acceptance criterion the defect defeats. Approving
+  would deliver work the spec does not accept.
+- `important` — name the acceptance criterion or stated invariant the defect
+  puts at material risk under realistic conditions, short of defeating it
+  outright.
+- `minor` — real and in scope, but nothing above turns on it.
+
+`blocking` and `important` both cost the producer a revision round, so if you
+cannot name that criterion or invariant, the finding does not belong at
+either level. A true defect that puts no acceptance criterion at risk, breaks
+no stated invariant, and is unreachable under realistic input is `ab observe`,
+not a finding — the same disposition an out-of-scope discovery gets.
+
+Do not raise a bar the spec set: where the spec bounds a failure model or an
+operating condition, conformance is measured against that bound, and a
+stricter model you would have chosen is not a defect. Hostile or pathological
+input that the surface's contract does not promise to handle is `minor` or an
+observation, unless a security boundary, an acceptance criterion, or a stated
+invariant makes it material.
+
+Approve when the plan would satisfy the spec — not when it matches how you
+would have written it. Known immaterial defects are not a reason to withhold
+approval — record them with `ab observe` and approve. Escalate when the
+*spec* is the problem (contradictory or unbuildable); revise when the plan
+is.

package/skills/reconcile/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: reconcile
+description: Resolve a conflicted PR by merging base into the build branch. Invoked by the build-runner as the reconcile phase; takes only the build slug.
+---
+
+# /ab-reconcile <build>
+
+The build's PR no longer merges cleanly: main moved. Your job is one merge
+commit — base merged *into* the build branch — that preserves both what this
+build was for and what landed on main since. **Never rebase**: rebasing
+re-resolves conflicts against a moving target and severs recorded SHA
+provenance, so it is banned in this system.
+
+## Session shape
+
+1. Run `ab context`. Read the manifest path printed by the command (normally
+   `.ab/context.json`) and use its `materialized` paths for the spec, plan, and
+   implement notes; legacy tracked paths may relocate them. It also contains
+   conflict info (`baseSha`) and — when a human answered an escalation a previous
+   attempt raised — `.ab/guidance.json`, their answer to it. Kernel plumbing
+   fetched the PR's configured base and resolved this SHA immediately before
+   your session, so the commit already exists locally; it is not the older
+   conflict-detection snapshot.
+2. `git merge <baseSha>` in the workspace and resolve every conflict with
+   the explicit charge to **regress against neither side**:
+   - The spec and plan tell you what this branch's changes are *for* — a
+     resolution that quietly drops the behavior they describe is a failed
+     reconcile, even if it compiles.
+   - The incoming base commits are already merged reality — a resolution
+     that undoes them will break main.
+3. Textual conflicts with one faithful resolution: resolve them. Then run
+   the repo's checks (typecheck, tests) — a merge that compiles but fails
+   tests is not resolved.
+4. Write the manifest's `notesPath` (normally `.ab/reconcile-notes.md`) with
+   each conflicted file, what collided, and why the resolution preserves both
+   sides; then run `ab done --notes <notesPath>`. The notes bytes reach the
+   store only through this flag; the file is never committed.
+
+   `ab done` requires the merge commit to exist and the worktree to be
+   clean; the push is plumbing. Verification re-runs in full afterward
+   because reconciliation changed code — that is expected, not a failure.
+
+## When not to resolve
+
+A **semantic** conflict — both sides changed the same behavior's meaning,
+the resolution needs a decision the spec doesn't make, or preserving both
+sides is impossible — escalates rather than guesses:
+
+```
+ab escalate "main's abc123 changed the session-token format; this build's rate limiter keys on the old format. Adopt the new format (touches spec criterion 3) or key differently?" --refs src/auth.ts
+```
+
+When an earlier attempt escalated and a human answered, `.ab/guidance.json`
+carries the escalation id and their answer. It is authoritative feedback for
+this attempt — resolve the way it says — while the spec remains the contract
+this phase is measured against; if the two cannot both be satisfied, escalate
+again rather than guess. Reconcile has no review round, so guidance is the only
+feedback it ever receives.
+
+Never stage or commit anything under `.ab/`, including with `git add -f`.
+Tracked legacy scratch needs no index flags or stash: leave it untouched and
+let the normal merge inherit, update, or delete it from a parent.
+
+A wrong guess here lands directly on main. Exactly one terminal command:
+`ab done` or `ab escalate`.

package/skills/spec/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: spec
+description: Design a feature spec-first through conversation, or flesh out an existing ticket to the spec standard. The human-interactive surface of the spec standard; creates or updates the ticket when done.
+---
+
+# /ab-spec [ticket]
+
+The conversational surface over the complete
+[spec standard](../ab-guide/references/spec-standard.md) installed with
+`ab-guide` — read it first. It defines "buildable": what and why but never how,
+verifiable acceptance criteria, explicit out-of-scope, and evidence. This skill
+runs *before* a build exists, so it takes a ticket, not a build slug — and
+unlike the phase skills, it is a conversation with a human, not an autonomous
+session.
+
+## Ticket operations
+
+Reach for `ab` first and use it whenever its CLI supports the requested ticket
+operation. That preference is about portability: `ab` is ticket-source
+agnostic, so it works across whatever `[tickets]` source the repository
+configures, while source-specific tooling is not portable across sources.
+Depart from `ab` only when the user asks for an operation outside its CLI
+surface. In that case, use the ticket tooling available in the current
+environment and tell the user what you changed.
+
+## No argument: design spec-first
+
+Interview the user toward a conforming spec. Work the standard's four parts
+in order, but as a conversation, not a form:
+
+1. **What and why.** Get the observable behavior change and the reason it
+   matters. Push back on solutions masquerading as problems ("add Redis" is
+   not a why). Read the relevant code as claims come up — ground the
+   conversation in what actually exists.
+2. **Acceptance criteria.** Propose them yourself from the discussion; let
+   the user correct. Each must be checkable by a reviewer or a verify step.
+3. **Out of scope.** Ask what adjacent work is explicitly excluded. Propose
+   candidates — the tempting expansions you noticed while reading the code.
+4. **Evidence.** Link what exists: the error rates, the user reports, the
+   prior discussion.
+
+Draft the spec in full, show it, iterate until the user accepts. Then create
+the ticket with the spec as its body using `ab ticket create`. Honor a
+destination workflow state when the human already named one during grooming:
+
+```
+ab ticket create "…" --body spec.md --state "<state>"
+```
+
+Do not ask a placement question solely to obtain a state, and do not infer one
+from the ticket. If grooming named no destination, omit `--state`; the create
+then uses `[tickets].createState`, or the ticket source's own default when that
+setting is absent.
+
+When the explicitly named destination equals `[tickets].readyState`, tell the
+human in the completion response that the ticket may be claimed by the next
+dispatch once the repository's label, dependency, intake, capacity, and other
+readiness gates are satisfied.
+
+If grooming established prerequisites, follow the complete
+[safe blocker-filing workflow](../ab-guide/references/ticket-dependencies.md).
+A single `ab ticket create --blocked-by` invocation does not publish atomically:
+Linear (including hosted Linear) exposes the issue before separate blocker writes.
+For a ready destination, create in a known non-ready staging state, pass all
+blockers at creation, read back and verify them, then move to ready last. The
+human's requested final placement still wins; temporary staging needs no new
+placement question. Never assume the source default is non-ready.
+
+For a dependency chain, create in dependency order and obtain each new id from
+the command's complete JSON result. This example assumes the repository's triage
+state is `Triage`, its ready state is `Ready`, and the human requested ready:
+
+```sh
+ab ticket create "A" --body a.md --json --state Triage > a-ticket.json
+a_id="$(jq -r '.ref.id' a-ticket.json)"
+ab ticket create "B" --body b.md --blocked-by "$a_id" --json --state Triage > b-ticket.json
+b_id="$(jq -r '.ref.id' b-ticket.json)"
+ab ticket create "C" --body c.md --blocked-by "$b_id" --json --state Triage > c-ticket.json
+c_id="$(jq -r '.ref.id' c-ticket.json)"
+ab ticket show "$b_id" --json
+ab ticket show "$c_id" --json
+# Verify both tickets remain in Triage and their full blocker sets are present.
+ab ticket move "$a_id" Ready --json
+ab ticket move "$b_id" Ready --json
+ab ticket move "$c_id" Ready --json
+```
+
+Never parse an id from the human-readable confirmation line: it can contain the
+new ticket id and blocker ids in the same source-local form. Dependency order
+alone does not close the ready-publication race. Blockers are evaluated when
+the dispatcher claims a ticket; adding a blocker
+after a ticket has already been claimed does not stop its active build.
+
+## With a ticket argument: flesh out
+
+Fetch the ticket. Diff it against the standard: which of the four parts are
+missing or unverifiable? Interview the user only on the gaps — don't
+re-litigate what the ticket already answers. Write the accepted conforming
+spec to a file, then sync only the body:
+
+```
+ab ticket update <ticket> --body spec.md
+```
+
+Omitted metadata is preserved, including title, labels, assignee, state, and
+provider-specific fields. If grooming changes dependencies, use the same
+configured-source surface rather than a provider API or MCP call:
+
+```
+ab ticket block <ticket> <blocker-id>
+ab ticket unblock <ticket> <blocker-id>
+```
+
+The first id is the ticket being amended. Both relationship operations are
+idempotent; adding validates the blocker exists and rejects a self-block.
+
+## Rules
+
+- The spec says **what and why, never how** — if the user hands you a
+  design, capture the underlying need and park the design in evidence as
+  "proposed approach", clearly non-binding on the planner.
+- Don't gold-plate: a spec is buildable when a planner could start, not when
+  every question is answered. Thin-but-groomed is a valid state — dispatch
+  can author the final spec if the ticket is honest about its gaps.
+- **Showing a draft ends the turn.** When presenting the spec (or any
+  ticket body) for review, make it the final text of your message and ask
+  for approval in prose — the user replies in chat. Never pair the draft
+  with a structured question tool (AskUserQuestion or similar) in the same
+  turn: text written before a tool call is not shown to the user, so they
+  would be asked to approve a document they cannot see. Reserve structured
+  questions for standalone decisions that don't depend on reading something
+  you just wrote.

package/skills/tickets/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: tickets
+description: Work this repo's local ticket tracker — create or edit a ticket, amend blockedBy dependencies, report the backlog, move work between triage/ready/doing/done, or answer "what's the status of ticket X". Use whenever the user asks about tickets, blockers, the backlog, or wants something queued for autobuild to build.
+---
+
+# /tickets
+
+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.
+
+## Where it lives
+
+`.autobuild/tickets/` by default (if `autobuild.toml` has a `[tickets] dir`,
+that directory instead), holding exactly four state directories:
+
+```
+.autobuild/tickets/
+  triage/   # filed, not groomed — the inbox
+  ready/    # groomed; file lifecycle-state gate satisfied
+  doing/    # claimed; a build is running
+  done/     # merged
+```
+
+**A ticket's state is the directory it is in.** There is no `state` field
+anywhere. Do not try to change a ticket's state by editing the file.
+
+Each ticket is `<id>.md`: TOML frontmatter between `+++` fences carrying `id`
+and `title` (and optional `labels` and `blockedBy`), then the body — which is
+the spec.
+
+## Create a ticket
+
+```
+ab ticket create "Rate-limit auth endpoints" --body spec.md [--labels bug,api] [--blocked-by file-1,file-2]
+```
+
+It lands in `triage/` and prints the new id. `--body` is a file, and its
+contents are the spec — write it to the complete
+[spec standard](../ab-guide/references/spec-standard.md) first (`/ab-spec` is
+the conversational way to get there). A ticket whose body isn't a conforming
+spec gets bounced back to `triage/` by the dispatcher rather than built.
+Blocker ids are source-local; every blocker must exist before creation
+succeeds.
+
+For dependencies on any source, follow the
+[safe blocker-filing workflow](../ab-guide/references/ticket-dependencies.md).
+Direct and hosted Linear record blockers after creating the issue, so a ready
+issue can be claimed before `create --blocked-by` returns. Stage dependents in a
+known non-ready state, verify all blockers with `ab ticket show --json`, then use
+`ab ticket move` to publish the intended ready destination. Do not use the local
+file tracker's default state as an assumption about another configured source.
+
+## Edit content or blockers
+
+Use the configured TicketSource rather than hand-editing frontmatter/body:
+
+```
+ab ticket update file-3 --body spec.md
+ab ticket update file-3 --title "New title" --labels bug,api
+ab ticket update file-3 --labels ''
+ab ticket block file-3 file-1
+ab ticket unblock file-3 file-1
+```
+
+Update is partial: omitted fields stay untouched, while an explicitly empty
+`--labels` clears labels. It cannot change state. For block/unblock the first
+id is the ticket being edited; the second is its blocker. Both are safe to
+retry, and adding validates the blocker exists and is not the ticket itself.
+
+## Report the backlog
+
+```
+ls .autobuild/tickets/ready     # groomed candidates in the ready lifecycle state
+ls .autobuild/tickets/doing     # what's building right now
+```
+
+The filename is the id. For a title, read the file's frontmatter. To report
+the whole backlog, list all four directories — that listing is complete and
+current by construction.
+
+## Groom / transition a ticket
+
+Move the file:
+
+```
+mv .autobuild/tickets/triage/file-3.md .autobuild/tickets/ready/
+```
+
+**Use `mv`, never `cp`.** A copy leaves the id in two state directories, and
+every ticket operation — including the dispatcher's scan — then fails loudly
+naming both paths. That is on purpose: the alternative is dispatching one
+ticket twice.
+
+Moving a file ticket into `ready/` satisfies the local file tracker's
+lifecycle-state gate. It makes the ticket a dispatch candidate; it does not
+guarantee an immediate claim. An unresolved `blockedBy` dependency prevents
+dispatch even when the ticket's state, labels, and spec otherwise qualify. The
+dependent stays in `ready/`, unclaimed and without a build.
+
+The dependency gate clears once every declared blocker has either reached the
+source's completed state (`done/` for the file tracker) or had its relationship
+deliberately removed with `ab ticket unblock file-3 file-1`. The dispatcher
+re-evaluates the dependent on a later tick; it can then become eligible without
+another move to `ready/`, subject to the remaining dispatch gates and available
+capacity. Blocker edits must use the source-agnostic `ab ticket block` and
+`ab ticket unblock` commands shown above.
+
+When the dispatcher claims an eligible file ticket, it moves it to `doing/`,
+then to `done/` on merge or back to `triage/` if the build aborts or the spec
+bounces.
+
+**Don't hand-move anything out of `doing/`** — a build owns it. If you need to
+stop a build, that's `ab` (or a human), not `mv`.
+
+## Rules
+
+- Never edit frontmatter to change state — the directory is the state.
+- Use `ab ticket update|block|unblock` for body, title, label, and `blockedBy`
+  changes; do not hand-edit those fields.
+- Never `git add` the tracker. The backlog is local-machine state, not shared
+  work; nothing here is published by committing it. (The default tracker
+  carries its own `.gitignore`, so git does not see it at all. Under an
+  explicit `[tickets] dir` the directory is the user's — it may well be
+  tracked — so the rule stands on its own either way.)
+- Ids are allocated by `ab ticket create`. Don't hand-write ticket files.
+
+## What is not here
+
+No default label gate for the file tracker: labels do not narrow the ready
+listing under default config. That does not make `ready/` sufficient;
+unresolved blockers are an independent dispatch gate.
+
+No Linear lifecycle UI. Directory-based lifecycle operations (`ls`, `mv`, and
+the four state directories) are file-tracker-only. If this repo's
+`autobuild.toml` sets `[tickets] source = "linear"`, do not apply that lifecycle
+guidance: state and labels live in Linear. The source-agnostic `ab ticket block`
+and `ab ticket unblock` commands still edit blocker relationships through the
+configured source.