doc-update: gascity-routing-model.md — the --on <formula> sling is an undocumented fourth delivery path: it routes the WISP ROOT (so the work bead legitimately has no gc.routed_to) and its --reassign is IsFormula-gated, leaving assignee residue that makes the bead invisible to pool demand (tk-wd9do)

[zook-bot]

Summary

Target

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

Change

• Add the formula sling (gc sling <target> <bead> --on <formula>) to the brief's
  lane taxonomy as its own delivery path, and state its field contract. The brief is
  the authority on "which routing field each delivery path is responsible for setting",
  but its three lanes only cover the bare sling, the direct --assignee write, and
  --reassign; the --on path behaves differently on BOTH fields:
  • gc.routed_to lands on the WISP ROOT, not the target bead. The routed bead is
    the wisp root (title = the formula name); the work bead legitimately shows
    gc.routed_to absent and assignee null even while it IS dispatched. That shape is
    normal, not evidence of a stranded/undispatched bead — and re-slinging on that false
    read creates a DUPLICATE wisp (two workers converging on one shared worktree). To
    check dispatch, look for the wisp root, not the work bead's routing.
  • --reassign does not clear the assignee on this path. The clear
    (reopenForReassignInStore) is gated by
    shouldReopenForReassign = opts.Reassign && !opts.IsFormula && !opts.DryRun, and
    upstream's own comment on the field calls --reassign "a guaranteed no-op on a
    fresh LaunchFormula, whose IsFormula route is skipped by shouldReopenForReassign".
    Lane 3 currently states the assignee clear unconditionally, and the --reassign
    idempotency subsection tells callers to "pass --reassign unconditionally and trust
    the routing call to be safe" — both need the formula-route caveat.
  • Why it matters (it fails silently): the pool's scale_check demand query counts
    only routed beads that are unassigned, so a formula re-pour that leaves assignee
    residue is invisible to demand and no worker spawns. A live worker's gc hook poll
    picks up routed+open beads regardless of assignee, so the stall shows up only when
    the pool is at zero — which is exactly when it is hardest to spot.
• Re-verify the predicate and the source locations at the pinned gascity revision before
  writing (the memory entry cites internal/sling/sling_core.go ~303-305 and ~1681-1695
  and internal/sling/sling.go ~273-277); cite what you confirm, not the remembered
  line numbers.
• Coordination note: live bead tk-qxocm also edits Lane 1 / Lane 3 assignee
  semantics (bare sling now clearing a stale assignee). Distinct provenance and a
  distinct claim, but the same lines — check whether it has landed and rebase/fold the
  wording rather than contradicting it.
• 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: two durable learnings in mechanik auto-memory describe the --on formula-sling
  delivery path's field contract — the doc's distinctive charge — but the brief has no
  coverage of it (no --on lane; "wisp" appears once, incidentally, in Lane 2; the
  unassigned-demand requirement appears nowhere).
• Source entry: reference-on-sling-routes-wisp-root-not-work-bead.md, reference-handback-repour-must-clear-assignee.md

Implementation notes

Implemented: added Lane 4 (gc sling <bead> --on <formula>) to docs/gascity-routing-model.md, plus subsections for the graph.v2 duplicate-wisp trap, the standalone-launch contrast, and the routed-AND-unassigned demand gate. +105/-4, docs-only.

VERIFICATION CORRECTED THE PREMISE. The bead asked to re-verify at the pinned revision; doing so showed its two central claims were inverted, and the doc now states the verified behavior instead:

1. '--on routes the WISP ROOT' is FALSE. --on routes the SOURCE bead and deliberately leaves the wisp root unrouted (TestOnFormulaAttachesAndRoutes, cmd/gc/cmd_sling_test.go:4105 asserts both halves; sling_core.go:488 'Do not fix this to wispRootID — it would orphan the work', gc sling --on <formula>: routed_to metadata set on origin bead instead of molecule bead gastownhall/gascity#2848). Routing the root is the STANDALONE LAUNCH shape (slingFormula, sling_core.go:373).
2. '--reassign is IsFormula-gated on --on' is FALSE. --formula and --on are mutually exclusive (cmd_sling.go:158) and AttachFormula leaves IsFormula false (sling.go:326), so the reassign reopen runs normally on --on. The guaranteed no-op is a standalone LaunchFormula, which is what upstream's own comment says (sling.go:273-279).
3. 'pool demand counts routed AND unassigned' is TRUE as filed (workquery.go:41-43).

The bead's operational conclusion survives via a different mechanism, which is what got documented: a graph.v2-attached work bead genuinely shows no gc.routed_to and no assignee while fully dispatched — not because routing moved to the wisp root, but because the graph path returns before the routing call (sling_core.go:477-481 -> doStartGraphWorkflow:645). Re-slinging on that misread still pours a duplicate wisp.

UPSTREAM MEMORY NEEDS CORRECTION (not actioned by me — polecat scope): the two cited source entries, reference-on-sling-routes-wisp-root-not-work-bead.md and reference-handback-repour-must-clear-assignee.md, conflate 'gc sling --on ' (attach) with 'gc sling ' (launch). Both attribute launch behavior to the attach path. Whoever owns that mechanik auto-memory should re-key them by path.

FORK-LOCAL SCOPE: cites canonical gastownhall/gascity only, pinned upstream/main 1dbf0731e. Per the operator ruling on sibling PR #209 ('Absolutely do not commit details about fork local routing models'), no fork-local content added; all four behaviors differentially confirmed identical in fork and upstream, so the canonical citation is also correct for the running city. Deliberately stays out of Lane 1/Lane 3 assignee semantics (tk-qxocm's territory) to avoid contradicting it.
Rework tk-52mw8 landed on polecat/tk-wd9do at 693b164; re-review tk-k0dw0 dispatched (one-anchor-per-PR, tk-ynz4b).

Refinery handoff

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

[zook-bot]

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

COMMENT on pre-open branch polecat/tk-wd9do at 693b1643cdfab7866dbd4166c800f30f73b6674d.

No blocking findings. Rework tk-52mw8 fixed the prior review issue: no stale three-lane, three lanes, All three, or broader three references remain in docs/gascity-routing-model.md; the two reviewed spots now say All four lanes and broader four-lane model.

Verified the corrected Lane 4 content against local Gas City commit 1dbf0731e: source-bead attach routing, unrouted attached wisp root, standalone launch routing, --formula/--on mutual exclusion, AttachFormula leaving IsFormula false, graph.v2 attach returning before routing, control-dispatch step routing stamps, and routed-plus-unassigned pool demand all match the document's claims.

Validation: git diff --check 8ce72df413c6278b00e05798c571bee6c9fa70db origin/polecat/tk-wd9do passed.

Review artifact: /tmp/compound-engineering/ce-code-review/20260724-051401-14521167/