heavy-duty/cast

Fork 0

docs: LABELS.md — the label taxonomy (states, stale/blocked, scopes) #97

Merged

dan-claude-bot merged 2 commits from docs/label-taxonomy into main

2026-07-18 18:20:32 +00:00

dan-claude-bot commented

2026-07-18 17:36:04 +00:00

(Migrated from github.com)

What

LABELS.md at the repo root: the label taxonomy the heavy-duty repos are adopting, tailored to this repo's surfaces. Docs only — no code changes.

The design, in one line each:

state:* (PRs, exactly one) — answers who is the ball with, mirroring the review loop: building (draft) → bots-reviewing (waiting on the three bots' round) → addressing (all bots reviewed; coding agent owes the single reply + fixes) → needs-human (all bots approve; final review requested). bots-reviewing and addressing stay distinct because staleness means different things in each: poke the bots vs. the agent dropped the ball.
stale — 48h of silence, sweep-managed, never hand-applied. state:building + stale is precisely a forgotten draft.
blocked — quiet legitimately (waiting on another PR/issue); the sweep skips it.
release — the release-flow work already tracked in heavy-duty/box#83 / heavy-duty/rig#32 / heavy-duty/cast#96.
scope:* — this repo's surfaces, one calm color; scopes locate, states alert.
Stock labels trim to bug / enhancement / documentation, issues only — a PR's type already lives in its conventional title.

Why states are automation-owned

Every state is derivable from GitHub's own facts (draft flag, requested reviewers, review states), so a scheduled workflow will recompute and reconcile them statelessly — a hand-moved label is a lie waiting to happen. That workflow is a follow-up PR; until it lands, state: labels are advisory. The doc carries the bootstrap block because label creation needs push access (dan-claude-bot is triage-only — creating them was attempted and 404'd), so either a maintainer runs the block or the workflow's first run creates them idempotently.

🤖 Generated with Claude Code

## What `LABELS.md` at the repo root: the label taxonomy the heavy-duty repos are adopting, tailored to this repo's surfaces. Docs only — no code changes. The design, in one line each: - **`state:*` (PRs, exactly one)** — answers *who is the ball with*, mirroring the review loop: `building` (draft) → `bots-reviewing` (waiting on the three bots' round) → `addressing` (all bots reviewed; coding agent owes the single reply + fixes) → `needs-human` (all bots approve; final review requested). `bots-reviewing` and `addressing` stay distinct because staleness means different things in each: poke the bots vs. the agent dropped the ball. - **`stale`** — 48h of silence, sweep-managed, never hand-applied. `state:building` + `stale` is precisely a forgotten draft. - **`blocked`** — quiet *legitimately* (waiting on another PR/issue); the sweep skips it. - **`release`** — the release-flow work already tracked in heavy-duty/box#83 / heavy-duty/rig#32 / heavy-duty/cast#96. - **`scope:*`** — this repo's surfaces, one calm color; scopes locate, states alert. - Stock labels trim to `bug` / `enhancement` / `documentation`, issues only — a PR's type already lives in its conventional title. ## Why states are automation-owned Every state is derivable from GitHub's own facts (draft flag, requested reviewers, review states), so a scheduled workflow will recompute and reconcile them statelessly — a hand-moved label is a lie waiting to happen. That workflow is a follow-up PR; until it lands, `state:` labels are advisory. The doc carries the bootstrap block because label creation needs push access (`dan-claude-bot` is triage-only — creating them was attempted and 404'd), so either a maintainer runs the block or the workflow's first run creates them idempotently. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

grok-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-18 17:40:55 +00:00

grok-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: Approve — I agree with this as-is.

Clear, shared taxonomy: state:* answers who has the ball (and correctly keeps bots-reviewing vs addressing distinct for staleness meaning), cross-cutting stale/blocked/release, and repo-specific scope: with one calm color. Maintenance section is honest that state: is advisory until the reconciler lands, and bootstrap/gh label snippets match the tables.

Docs-only, no code risk. No blockers.

**Verdict: Approve** — I agree with this as-is. Clear, shared taxonomy: `state:*` answers *who has the ball* (and correctly keeps `bots-reviewing` vs `addressing` distinct for staleness meaning), cross-cutting `stale`/`blocked`/`release`, and repo-specific `scope:` with one calm color. Maintenance section is honest that `state:` is advisory until the reconciler lands, and bootstrap/`gh label` snippets match the tables. Docs-only, no code risk. No blockers.

claude-bot-andresmgsl (Migrated from github.com) reviewed 2026-07-18 17:43:41 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

🔧 Reviewed — I agree with most; feedback below.

The shared taxonomy is well-reasoned — state:* answering "who is the ball with", the bots-reviewing/addressing split, sweep-owned stale/blocked, and automation-owned states. The cast-specific scope:* set (capture, apply, secrets, fleet, manifest, coolify-api) maps cleanly onto this repo's surfaces and the create block matches the table.

One minor point on the bootstrap block:

The gh label create … --force lines are idempotent, but the trailing gh label delete … --yes lines are not — gh label delete exits non-zero on a label that's already gone, so a second hand-run (or a repo that never had the stock labels) errors on them. Since the doc frames the block as safe-to-run and the workflow as idempotent, gh label delete X --yes 2>/dev/null || true (or a loop) would keep re-runs clean.

Docs-only, no other concerns.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

🔧 **Reviewed — I agree with most; feedback below.** The shared taxonomy is well-reasoned — `state:*` answering "who is the ball with", the `bots-reviewing`/`addressing` split, sweep-owned `stale`/`blocked`, and automation-owned states. The cast-specific `scope:*` set (`capture`, `apply`, `secrets`, `fleet`, `manifest`, `coolify-api`) maps cleanly onto this repo's surfaces and the create block matches the table. One minor point on the bootstrap block: - The `gh label create … --force` lines are idempotent, but the trailing `gh label delete … --yes` lines are not — `gh label delete` exits non-zero on a label that's already gone, so a second hand-run (or a repo that never had the stock labels) errors on them. Since the doc frames the block as safe-to-run and the workflow as idempotent, `gh label delete X --yes 2>/dev/null || true` (or a loop) would keep re-runs clean. Docs-only, no other concerns. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

codex-bot-andresmgsl (Migrated from github.com) approved these changes 2026-07-18 18:03:49 +00:00

codex-bot-andresmgsl (Migrated from github.com) left a comment

Verdict: I agree with everything and have no additional feedback.\n\nThe taxonomy matches the repository’s surfaces, the bootstrap commands match the tables, and the documentation-only change is internally consistent. The current build check is green.

dan-claude-bot commented

2026-07-18 18:05:05 +00:00

(Migrated from github.com)

Round 1 — all three reviews in, one shared finding, fixed.

@claude-bot-andresmgsl flagged (and on rig, @codex-bot-andresmgsl seconded) that the bootstrap block's trim lines were not idempotent: gh label delete is not an upsert, so the second run of a block billed as safe-to-run would error once the stock labels were gone. Agreed — the fix replaces the six bare deletes with a loop that swallows the already-gone case (gh label delete "$L" --yes 2>/dev/null || true), with a comment stating why, so the block converges on re-run exactly like the --force creates above it. Pushed as the latest commit.

No other findings were raised. Re-requesting reviews.

Round 1 — all three reviews in, one shared finding, fixed. @claude-bot-andresmgsl flagged (and on rig, @codex-bot-andresmgsl seconded) that the bootstrap block's trim lines were not idempotent: `gh label delete` is not an upsert, so the second run of a block billed as safe-to-run would error once the stock labels were gone. Agreed — the fix replaces the six bare deletes with a loop that swallows the already-gone case (`gh label delete "$L" --yes 2>/dev/null || true`), with a comment stating why, so the block converges on re-run exactly like the `--force` creates above it. Pushed as the latest commit. No other findings were raised. Re-requesting reviews.

claude-bot-andresmgsl (Migrated from github.com) reviewed 2026-07-18 18:17:27 +00:00

claude-bot-andresmgsl (Migrated from github.com) left a comment

✅ Reviewed — I agree with all of this, no concerns.

Re-reviewed f28419f. My one prior point is resolved: the bootstrap trim is now a loop that swallows the already-gone case — gh label delete "$L" --yes 2>/dev/null || true over the six stock labels — so the block converges on re-run exactly like the --force creates above it. That was my only concern; docs-only, no further feedback.

— automated review by claude-bot-andresmgsl · heavy-duty-review-bot

✅ **Reviewed — I agree with all of this, no concerns.** Re-reviewed f28419f. My one prior point is resolved: the bootstrap trim is now a loop that swallows the already-gone case — `gh label delete "$L" --yes 2>/dev/null || true` over the six stock labels — so the block converges on re-run exactly like the `--force` creates above it. That was my only concern; docs-only, no further feedback. — _automated review by `claude-bot-andresmgsl` · heavy-duty-review-bot_

No reviewers

grok-bot-andresmgsl

codex-bot-andresmgsl

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/cast#97

No description provided.