Skip to content

t1k:ual-label

FieldValue
Modulet1k-ual
Version2.9.56
Efforthigh
ToolsBash, Glob, Grep, Read, Skill, Workflow

Keywords: asset labelling, index new assets, label assets, label new assets, re-label ladder, relabel assets, ual label, ual labelling, ual-derive-tags, ual-label-gate, ual-label-ladder, ual-label-round

/t1k:ual-label
<scope: new assets | re-label cells> [--engine cocos|unity]

Indexes and labels new assets in the studio catalogue the same way the 2026-10-05 run did: cheap models first, a gate that proves they are good enough per cell, a strong model only for the residual. Lookup of existing assets is t1k:ual; this skill WRITES labels. Labelling lanes run as t1k-ual-labeller agents.

Every command runs from a UniversalAssetLibs checkout (quote the path; it contains a space). The runbook is the asset-labelling page in that repo’s docs folder; the CLIs are ual-derive-tags, ual-label-round, ual-label-gate and ual-label-ladder in packages/ual-cli/bin/. Read the runbook and each CLI’s --help before the first run: flags below are the contract, the repo is the truth.

Before the first UAL call: run bun .claude/scripts/ual-netbird-preflight.cjs (t1k-ual § “Before the first UAL call”). A NetBird Service HTML 502 means the browser login is missing, not an outage.

  1. Preview-first sizing. Count rows to label, estimate lanes (50-row chunks, 5-20 min each, cap 16 parallel) and cost; show a small smoke sample; get an explicit user go-ahead via AskUserQuestion before scaling (rules/preview-first-batch.md).
  2. r1 — ual-derive-tags run: the deterministic first rung. No model.
  3. Model-A round — ual-label-round prepare on r1 needs-review rows plus the gold keys, labelled by deepseek-v4.1-flash (the router default, no modelDirective).
  4. Gate — ual-label-ladder gate-inputs --gold <round>... --tagger <name>=<rounds> --out <dir>, then ual-label-gate assess.
  5. Agreement vs gold, model B = the free commandcode/laguna-s-2.1-free: ual-label-ladder agreement --gold <round>... --a <rounds> --b <round> [--exclude keys.json] prints engine x category PASS cells.
  6. Rung-1 round — ual-label-ladder select --round <rounds> --cells engine:category,... --rows <scan rows>... --out rows.json selects rows in passing cells; label them with model B.
  7. Accept consensus (A and B agree). prop and every other failing cell go to a strong-model residual round: capped, and the cap approved by the user first.
  8. Merge the accepted rounds into the index (ual-label-round ingest, then the runbook’s merge step).

Gold rule: a cell needs >= 10 gold rows or it is insufficient-sample, never PASS. Top up with a strong-model gold round.

Steps 3 to 7 (stratified gold draw, strong-model gold round, blind audit, model-B routed hops, then the ual-label-ladder and ual-label-gate CLIs) are orchestration. They run in the invoking session, or an opus lane started from it, because that session holds the Workflow tool and the Agent fan-out; no installed agent declares Workflow, and t1k-ual-labeller is a one-batch haiku leaf. No orchestrator agent exists by design (cheap agents are leaves, skills/t1k-agent-creator/references/architecture-rules.md section 0.3). A generic claude lane running these rungs is the expected shape: do not create an orchestrator agent for it, and do not sharpen t1k-ual-labeller toward it (its charter is one batch file).

Pre-flight: the write-agent floor (run before the first Workflow dispatch)

Section titled “Pre-flight: the write-agent floor (run before the first Workflow dispatch)”

t1k-ual-labeller holds the Write tool, so the model-router’s write-agent floor gates every labelling hop — EXCEPT on kits whose installed agent declares writeScope: reports (core#6486): a report-only writer is never floored, whatever the floor value, and the pre-flight below is a no-op. Confirm the declaration once, then skip the rest of this section:

Terminal window
grep -n "writeScope: reports" .claude/agents/t1k-ual-labeller.md

When the installed agent does NOT declare it (an older kit), the resolved floor decides. When the resolved writeAgentFloor covers write agents and the labeller is not in routableWriteAgents, the router answers MR-PROXY: NOT-ROUTABLE (kit-policy-write-agent) for every chunk, the Workflow reports the whole round failed, and the fan-out spend is wasted. Check the resolved floor BEFORE running the Workflow:

Terminal window
# fragments merge by priority within a scope, then project beats home; an absent
# writeAgentFloor key means the router's in-code default, which is "all"
grep -H '"writeAgentFloor"\|"routableWriteAgents"' ~/.claude/t1k-config-mr*.json .claude/t1k-config-mr*.json 2>/dev/null

BLOCKED when the winning fragment has writeAgentFloor: "all" (explicitly, or by omission — the default is "all" and routableWriteAgents ships empty) while routableWriteAgents does not list t1k-ual-labeller. In that state every chunk fails; do not start. The fix, cheapest first:

  1. Add "t1k-ual-labeller" to routableWriteAgents in your t1k-config-mr.json — keeps the cheap label model (the ladder’s whole point).
  2. Set writeAgentFloor: "premium-only" for the run — every hop then runs natively on the labeller’s haiku pin. The round completes, at native-model cost.

A round that already failed with MR-PROXY: NOT-ROUTABLE (kit-policy-write-agent) labelled nothing (no result files were written, nothing ran natively): fix the floor first, then re-run the Workflow for those chunk ids exactly as for a fresh round.

Routing contract (core#6486): t1k-ual-labeller declares writeScope: reports — its only mutating tool is Write, confined to the result files — so the model-router write floor (writeAgentFloor, including its shipped 'all' default) never holds it native, and the routed hops reach the cheap label model on a stock install. If a round still answers MR-PROXY: NOT-ROUTABLE (kit-policy-write-agent), the install’s agent file predates the declaration: run t1k modules update (or add writeScope: reports to the installed t1k-ual-labeller.md).

ual-label-round prepare writes <root>/batches/<chunk>.jsonl. Then run the shipped Workflow with the Workflow tool, script scripts/ual-label-batches.workflow.js.txt (this skill’s directory) (a Workflow script body with top-level await/return, shipped as .js.txt so CI’s module syntax gate does not parse it as a module; pass its contents as the script), args {root, chunks, modelDirective} (modelDirective omitted for model A, e.g. commandcode/laguna-s-2.1-free for model B). It returns {failed, wrongModel, deferred, notRoutable, pending}; a deferred chunk was refused by the router fan-out gate (MR-PROXY: NOT-STARTED), is not labelled, never ingested and never run natively. The workflow cannot sleep: wait several minutes (at least 5), then re-run the workflow with chunks set to the deferred ids only. A notRoutable chunk was refused by the write-agent floor (MR-PROXY: NOT-ROUTABLE) — no amount of waiting or retrying fixes it; run the pre-flight above, fix the floor config, then re-run the workflow for those ids. pending maps a chunk to the proxy id of a hop that is still running (MR-PROXY: PENDING id=<id> handback; its result file is not written yet): before execute/ingest, run the mr-proxy-run.cjs --wait <id> call that handback line prints, for each one, repeating while the last line still starts with MR-PROXY: PENDING. Never re-run a pending chunk through the workflow (that spawns a duplicate hop); with a pinned model, a waited reply without the model=<pinned> marker is wrongModel.

  1. Quarantine every chunk in wrongModel BEFORE ingest: move its result file aside, because its labels are from the wrong tagger and would be ingested under the wrong id.
  2. ual-label-round execute, then ingest.
  3. Re-run the re-queue batches ingest emits (schema-invalid rows) through the Workflow once more.
  • No full run without the preview-first go-ahead; no strong-model spend without the user-approved cap.
  • Never ingest a wrongModel chunk. Never report a cell as passing on < 10 gold rows.
  • This skill labels; asset lookup, pull and hold status stay with t1k:ual.