doc-update: gascity-routing-model.md — document the claim predicate (status=open + gc.routed_to): hold/park metadata such as rebase_hold/hold_reason is inert documentation, so a "held" bead is still offered and claimable (tk-16753)

[zook-bot]

Summary

Target

• Brief(s): docs/gascity-routing-model.md

Change

• Document the claim predicate — the read side the three lanes are writing for.
  The brief specifies which field each delivery path sets, but never states what makes a
  bead claimable, so the enforcement boundary is left implicit.
• State it explicitly: a bead is offered to a pool worker on status=open +
  gc.routed_to=<pool>; arbitrary metadata is not part of the predicate. The consequence
  is the non-obvious part and belongs in this brief: bespoke hold/park flags such as
  rebase_hold=true / hold_reason="..." are documentation, not enforcement — a
  bead carrying them is still offered and can be claimed by a hooked worker. To actually
  hold a bead you must remove it from the predicate: clear gc.routed_to and move
  status off open (e.g. blocked). The metadata explains the hold; it never imposes
  one.
• Worth stating here because the failure is silent and asymmetric: the agent that
  stamped the flag believes the bead is parked, and only the worker that claims it
  anyway discovers otherwise.
• If the sibling bead on the --on formula-sling path lands too, keep the two
  consistent: pool demand counting adds unassigned to the predicate, so the offer
  predicate and the demand predicate are related but not identical — say which is which
  rather than blurring them.
• Re-verify the predicate against the current hook/pool implementation before writing
  rather than copying the memory entry's wording.
• The audit does not write the final prose: the worker promotes the learning into the
  named brief(s). If the entry carries operator PII, internal URLs, or absolute home
  paths, paraphrase rather than promoting verbatim. If review shows the fact is already
  covered or does not belong, close as a no-op.

Provenance

• Gap: a durable learning in mechanik auto-memory states the claim predicate and that
  hold metadata is inert — squarely inside the mandate of the brief that is the
  authority on the field-level routing contract — but the brief documents only the
  write side and never the predicate those writes feed.
• Source entry: reference-bead-hold-needs-status-and-routing-not-metadata.md

Implementation notes

Implemented: added 'The read side: the claim predicate' to docs/gascity-routing-model.md — the tiers mapped onto the lanes, the pool term table (open + no active blockers + gc.routed_to + unassigned + not epic), offer/demand as ONE predicate read two ways, 'metadata is not enforcement' (bespoke rebase_hold/hold_reason flags are inert; the bead stays offered and claimable), and how to actually hold (clear gc.routed_to AND assignee, or move status off open). Re-verified against the RUNNING implementation per the bead, which corrected the bead's own framing: it expected demand to add 'unassigned' to an offer predicate lacking it, but both tiers carry --unassigned, so offer and demand are the same predicate differing only in answer shape. COORDINATION: PR #209 (tk-qxocm) is in flight on the same file and states the shared predicate in passing; this adds the named section plus the inert-metadata consequence #209 does not cover. Both append a Provenance row — expect a trivial both-added conflict there on rebase. Sibling tk-wd9do (--on formula-sling path) is still open and unstarted.
Rework tk-e96i8 landed on polecat/tk-16753 at 2b808ff; re-review tk-lq3aq dispatched (one-anchor-per-PR, tk-ynz4b).

Refinery handoff

• Issue: tk-16753 (task, P2)
• Source branch: polecat/tk-16753
• Target: main
• Codex signed off pre-open at 2b808fff; PR opened codex-green.

[zook-bot]

Codex signoff (pre-open, comment-only — not an approval):

Code Review Results

Scope: origin/main (e8435241a4c5a1db7c7bedb6ddfc999952b846d6) -> origin/polecat/tk-16753 (2b808fffbf0061376400d67c87d035bc26be7e5a), 1 file
Intent: Document the gc hook read-side claim predicate in docs/gascity-routing-model.md, including why arbitrary hold metadata is inert and how to remove beads from the actual offer/demand predicate. Re-review after tk-e96i8 split Tier 1 in-progress recovery from Tier 2 ready assigned work.
Mode: pre-open branch signoff

Reviewers: correctness, testing, maintainability, project-standards, agent-native, learnings

• correctness -- verified the prose now distinguishes bd list --status=in_progress --assignee recovery from bd ready --assignee assigned-ready work and keeps routed-pool work on gc.routed_to + --unassigned
• testing -- checked diff hygiene for the Markdown-only branch
• maintainability -- checked the new section fits the existing three-lane structure and avoids duplicating docs/gascity-agents.md
• project-standards -- no AGENTS.md or CLAUDE.md standards files were present in scope
• agent-native -- the change improves agent-facing routing guidance and does not add an inaccessible workflow surface
• learnings -- compared against the prior failed review tk-d944i and rework bead tk-e96i8

Findings

No actionable findings.

Coverage

• Reviewed changed file: docs/gascity-routing-model.md
• Verified previous rework target: prior review tk-d944i asked to split Tier 1 in-progress assignee recovery from Tier 2 ready assignee work; the branch now does that.
• Verified adjacent docs: docs/gascity-agents.md already names the same three hook tiers, and docs/work-bead-state-machine.md agrees that gating detaches a bead with assignee="" and gc.routed_to="".
• Verified live CLI surface: gc hook --help, gc bd ready --help, gc version, and resolved gc config show for the proactive work/demand query.
• Validation: git diff --check e8435241a4c5a1db7c7bedb6ddfc999952b846d6 2b808fffbf0061376400d67c87d035bc26be7e5a passed.
• Tests: no repo-level Markdown/docs test command was found for this documentation-only change.
• Subagent note: reviewer dimensions were run locally because the available subagent tool policy requires an explicit user request for delegation.

---

Verdict: Ready to merge

Reasoning: The rework addresses the previous P2 finding, the documented predicate matches the observable CLI/config behavior, and the hold guidance now avoids implying that bd ready is the whole hook.