Skip to content

Personal Linear status guard: agents may make listed forward moves

  • Date: 2026-11-05
  • Status: Accepted
  • Tags: tooling workflow

Context

The work harness has linear_status_guard.py: only a human changes a Linear issue's status, and agents propose Done or Cancel with a label. It was never installed on the personal laptop, so there agents could move an issue to any status, and they often picked the wrong one.

The personal flow needs something in between. A task typed in the daily note with a 📅 date gets a Linear issue under its project, and that issue must be In Progress by the end of that day; a close-day check reports any that aren't. Agents picking up the work should be able to make that move, but not close, reopen or move work backwards.

Two facts shaped where the change goes:

  • claude/harness/ is a generated copy of the work laptop's ~/.claude, rewritten weekly (ADR 0033). An edit there would be overwritten, and would change the work laptop's rule.
  • Linear statuses have the same names on the PHA and DEV teams but different ids, and the Linear MCP tools take a status name, type or id.

Decision

A personal copy of the guard, claude/hooks/linear-status-guard.py, installed with just linear-status-guard-install like the work-tracker hook (ADR 0040).

  • Per-machine policy. ~/.claude/linear-status-policy.json lists the allowed [from, to] moves and the statuses an issue may be created in. The default: Backlog → Todo, Backlog or Todo → In Progress, In Progress → In Review; create as Backlog, Todo or In Progress. No file, or an unreadable one, means strict: the work guard's behaviour.
  • Fixed floor. Moving to Done, Canceled or Duplicate, and moving out of them, stays blocked whatever the policy says. Raw GraphQL status mutations and lb close/cancel/delete/auto stay blocked.
  • Judged from the live status. The hook reads the issue's current status and its team's statuses from Linear before allowing a move, and blocks if that read fails. Names match in any case and ids resolve through the team; a status type such as started is refused.
  • lb gets the same check, but only as a plain single command, so the guard knows which issue and status it is judging.
  • Every status decision is logged to ~/.claude/logs/linear-status-guard.jsonl, as the first data on where agents try to move work.

Alternatives Considered

Option Why Rejected
Install the work guard unchanged Blocks the one move the daily-note flow needs agents to make
Edit claude/harness/hooks/linear_status_guard.py Generated mirror of the work laptop; overwritten weekly, and would change the work rule
Allow by target status only, no Linear read Can't tell a forward move from a reopen or a backward move, which are the wrong moves we were seeing
Rely on Linear's GitHub automation alone Covers code work only; non-code tasks have no branch or PR

Consequences

Positive:

  • Agents can start work (In Progress) on this laptop, and nothing else that was a problem.
  • Each allowed move is checked against where the issue really is, not where the agent thinks it is.
  • The log gives a record of attempted moves for the self-improvement loop.

Negative / Trade-offs:

  • Two copies of the guard now exist; a fix to one has to be carried to the other by hand.
  • Each status write costs a Keychain read and one Linear call (both capped at 5 seconds).
  • lb update -s inside a compound command is refused even when harmless.

Ongoing obligations:

  • When the work harness guard changes, compare it with the personal copy.
  • If a team adds or renames a status, update the policy file.

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.