Personal Linear status guard: agents may make listed forward moves¶
- Date: 2026-11-05
- Status: Accepted
- Tags:
toolingworkflow
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.jsonlists 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/autostay 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
startedis refused. lbgets 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 -sinside 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.