git:20261112.5cb1293 to git:20261115.8a8883f

40 added, 81 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Tracking work in a Punt Labs repo
How an agent tracks work in a Punt Labs repo. punt-kit deposits this file;
edit the source in punt-kit (`src/punt_kit/templates/punt-guide.md`), never
this copy. The normative text is the punt-kit repo's `standards/workflow.md`
§ 4 (the backlog loop) — the org standard, not your repo's own
`docs/WORKFLOW.md`; this file is the operating rule that section leaves to the
tracker.
- Two trackers exist. **Beads** is the local issue database behind the `bd`
- command; one issue in it is a *bead*. **Linear** is the hosted tracker, used
- from its web app or from the Linear MCP tools when your harness has them: one
- team, **Punt Labs**, key `PL`, id `c1dfbb2c-985e-40cf-b004-5127646efc9d`. A
- *pull* copies Linear into beads; a *push* copies beads into Linear.
-
- ## Which tracker is the record here
-
- Run `bd config get linear.pull_label`. Output starting with `repo:` means this repo is migrated and
- Linear is the tracker of record. Anything else means beads is. `bd config get issue-prefix` cannot
- tell you: it prints `issue-prefix (not set)` on migrated repos whose `.beads/config.yaml` has the key.
- Nor can `bd linear status`: it prints `Status: Not configured` on a working setup. The migrated set
- is `bd config get linear.push_prefix`, read live; it is maintained nowhere else. If the output is not
- `repo:` but this repo prefix is in `linear.push_prefix`, this checkout is behind main: pull it and
- re-run; until then do not write to beads.
+ **Linear** is the tracker of record for every Punt Labs repo: the durable,
+ cross-session source of truth for what work exists and what state it is in.
+ One hosted team holds all of it — **Punt Labs**, key `PL`, id
+ `c1dfbb2c-985e-40cf-b004-5127646efc9d`. Reach it from the Linear web app, or
+ from the Linear MCP tools when your harness has them (`list_issues`,
+ `save_issue`, `list_comments`, and the rest). An issue is addressed by its
+ identifier, e.g. `PL-1051`.
- ## Migrated repos: Linear is the record
+ One team holds every repo's work, so an issue carries a **repo label** —
+ `repo:<name>`, e.g. `repo:punt-kit` — that says which repo owns it. Every
+ read and every write names that label, so this repo's issues stay separate
+ from the rest of the team.
- Beads is a read-mostly local mirror. Do not use it as the record when Linear
- is available. Every migrated bead stores its Linear URL in `external_ref`.
+ ## Which issues are this repo's
- - **Plan from Linear.** `bd ready` and `bd show` are fine as local reads
- because the mirror carries the dependency graph; `bd list` and `bd ready`
- need `--label-any <the repo label>` to stay inside this repo, because the
- shared database holds every repo's beads. Before the first pull, check the
- installed `bd`: it must be built from the punt-labs fork at or after
- punt-labs/beads#8 (commit `769f8a1`). Take the commit `bd version` prints
- and confirm `git merge-base --is-ancestor 769f8a1 <that commit>` in the
- fork clone (`.bin/install-bd.sh install` in the punt-labs/punt-labs
- meta-repo clones the fork into `.tmp/beads-fork/` and installs
- `~/.local/bin/bd`); if it is not, rebuild before pulling. Earlier builds
- ignore or only partly honour `linear.pull_label` and write other repos'
- Linear issues into the shared database as this repo's beads. Then refresh
- the mirror:
- `bd linear sync --pull-if-stale --relations --team c1dfbb2c-985e-40cf-b004-5127646efc9d`
- pulls only when `.beads/last_pull` is missing or older than 20 minutes, never
- twice within 5 minutes (needs `LINEAR_API_KEY`). `--relations` imports added
- `blocks` edges; a pull removes none, so a blocker cleared in Linear still
- blocks locally until you run `bd dep remove <bead> <blocker>`. Until both the
- add and the removal are reconciled, `bd ready` can disagree with Linear.
- Auto-pull (`bd prime` pulling on its own at session start) is not on in every
- repo; never assume it ran. Do not turn it on in a repo until the installed
- `bd` has passed the build check above: an auto-pull runs before any agent
- can check, so an older build contaminates the shared database unattended.
- - **Write in Linear, not beads.** Create an issue with the mandatory repo
- label (the value `bd config get linear.pull_label` printed) plus a type
- label (`Bug`, `Feature`, `Improvement`, `Epic`); a pull imports only issues
- carrying that repo label. Edit title, description and priority there. Claim, finish
- and cancel with the states In Progress, Done and Canceled. Labels, `blocks`
- relations and projects are Linear-only.
- - **Three proven facts about sync.** A push sends no labels. A pull replaces a bead's label set
- with the issue's, so a beads-only label is wiped. A pull resets a bead's status to the issue's
- state, so a `bd close` made only in beads is undone by a later pull (the cursor bullet says when).
- - **Blocked** means a `blocks` relation in Linear plus `bd dep add <bead>
- <blocker>`: a pull imports relations only with `--relations`, removes none.
- - **Deferred** means state Backlog plus the `deferred` label; pick work with
- `bd ready --label-any <the repo label> --exclude-label deferred` (the repo
- filter keeps it inside this repo, as every migrated read does).
- - **Automated loops** write status in Linear, then refresh the bead with a
- scoped `bd linear sync --pull --issues <PL id> --team <id>` — never a local
- `bd update`/`bd close`, which is the forbidden local edit below and strands
- other Linear changes to the same issue.
- - **The one sanctioned beads-first write** is `bd linear sync --push --issues
- <bead ids> --team <id>` (title, description, priority, state only); then add
- labels in Linear, then `bd linear sync --pull --issues <PL ids> --team <id>`.
- - **One cursor per repo label, shared by push and pull.** It is a saved timestamp; an incremental pull
- fetches only Linear changes after it, and every non-dry-run sync in this repo, a push included,
- moves it. A push hides Linear edits since the last pull from this repo's next incremental pull, not
- another repo's. Never edit a migrated bead locally, `bd close` included: the next pull, scoped or
- not, skips a bead edited after the cursor and moves the cursor past it; a later pull that fetches
- the issue (on its next Linear change, or by `--issues`) overwrites the bead, status included.
- - **Never:** a bare `bd linear sync`; an unscoped `--push`;
- `bd config set linear.*` (shared by every repo); removing `issue-prefix` or
- `linear.pull_label` from `.beads/config.yaml` (an unscoped pull imports the
- whole PL team).
- - **ID bridge.** Bead to Linear: `bd show <id>` prints the `external_ref` URL. Linear to bead:
- `bd list --json --all --limit 0 --label-any <the repo label>` and match on `external_ref`.
+ List with the repo label to stay inside this repo:
+ `list_issues` filtered by team `PL` and label `repo:<name>` (the web app's
+ label filter does the same). The repo label is the one scoping key; nothing
+ else distinguishes one repo's issues from another's on the shared team.
- ## Beads-only repos: beads is the record
+ ## Working an issue
- `bd create`, `bd ready`, `bd show`, `bd update <id> --status in_progress`, `bd close`. Labels and
- dependencies live in beads. To migrate, use the `linear-migrate` skill in the workspace: the
- punt-labs/punt-labs meta-repo, whose `.claude/skills/` holds it — one directory above a child repo,
- or this repo itself when the guide is deposited in the workspace.
+ - **Plan from Linear.** List open, unblocked issues for this repo
+ (`list_issues` by team `PL`, label `repo:<name>`, status not Done/Canceled)
+ and read one with `get_issue`. `list_comments` returns an issue's
+ discussion — `get_issue` does not include it.
+ - **Create** an issue on team `PL` with `save_issue` (omit `id` to create),
+ carrying the mandatory `repo:<name>` label plus a type label — `Bug`,
+ `Feature`, `Improvement`, or `Epic`. Give it a clear imperative title, a
+ description another engineer or agent can act on, and a priority. Statuses
+ and labels belong to the team; call `list_issue_statuses` or
+ `list_issue_labels` for `PL` when unsure which values it supports.
+ - **Claim, finish, and cancel** by setting the issue's status — In Progress,
+ Done, Canceled — with `save_issue` (pass `id` to update, and only the
+ fields you change). A session task list mirrors the claimed batch for the
+ operator; the Linear issue is the record.
+ - **Blocked** is a `blocks` relation in Linear between the blocker and the
+ blocked issue. Pick work whose blockers are all Done.
+ - **Deferred** is state Backlog plus the `deferred` label; skip deferred
+ issues when picking the next unit.
+ - **Edit** title, description, priority, labels, relations, and projects in
+ Linear. To change part of a long description, pass `patch` to `save_issue`
+ rather than resending the whole body. `addLabels` / `removeLabels` adjust
+ one label without dropping the rest; the `labels` field replaces the whole
+ set.
## Both
- T4 work (a typo, a one-line fix, a mechanical refactor with no design
choice) needs no issue; the commit is the record.
- Work is not complete until `git push` succeeds.
- - Beads mechanics: the workspace `.docs/BEADS-SETUP.md`.
- - Migration and reversal: the workspace `linear-migrate`, `beads-to-linear` and `linear-unmigrate` skills.