amd-agi/geak/gluon-authoring

When to use

The workflow is working a Gluon kernel on gfx942/gfx950 and needs two things this file supplies: the Gluon API surface, and the do-not-write list — the constructs and instruction choices that compile and then silently cost you.

Two entry states, and they do not open the same way:

• Porting from plain Triton (from_backend: triton). A tuned plain kernel exists, so the opening move

is the fixed transcribe-then-re-inject pair in ## Procedure, closing against that kernel at ≥95%. That bar is a checkpoint the track passes through; step 4 is what the port was for.

• Already Gluon (from_backend: gluon). Nothing to transcribe and no plain comparator to hold parity

with, so skip step 1 and step 3's checkpoints, and read step 4 as the whole procedure rather than as a continuation (its preamble says which of its items are port-only). Step 2 is still available, but as an ordinary lever rather than a debt to repay, and it is entered differently:

• Step 2a does not apply — there is no plain side to turn off, so there is no plain@ns=1. Ask

the IR instead whether this loop already overlaps, using the tell that matches its shape (step 2d): ttg.memdesc_index only where the loop has a dot; iter_args 0→1 plus load-count scaling where it does not, because memdesc_index is 0 on a dot-free loop by construction.

• If it does not overlap and the loop has a dot, steps 2b–2d apply unchanged: the re-injected

pipeliner is the cheapest way to add it, and it will build the LDS staging itself.

• If it does not overlap and the loop is dot-free, the pipeliner has nothing to anchor on. That is

the authored-overlap case, and on CDNA3 the surface is sync staging (allocate_shared_memory + .store()/.load() + barrier) plus the warp_pipeline_stage hint — not async copy, which does not lower on gfx942 at all. See `references/gluon/pipeline-reference.md` ## Authored overlap, and ## Knobs & pitfalls here for what is unavailable despite importing.

• If it already overlaps, the pipeline layer is closed; go to step 4.

Run steps 1–4 as one continuous track held by one agent, not as a fan-out. Two reasons, and they are different. The porting moves are deterministic: any two agents transcribing the same pinned .ttgir land on the same layouts, so parallel arms do not explore alternatives — they all measure the same transcription, and a shared bug in it identically. And the continuation in step 4 is stateful: what to try next is chosen from the IR and profile of the anchor you just built, which the agent that built it is holding and a fresh agent would have to rebuild. Splitting the track at the gates throws that away at the moment it becomes useful.

What the track needs from the caller. This skill owns no budget model, but the port has a shape the round loop has to be told about: a transcription lands below the comparator and climbs back, and at the stock defaults that phase is not representable at all — the transcription round produces no candidate, so no patch is saved, no verify runs, and the loop stops two rounds in. There is no "port mode" to switch on; there are launch args, and a port is a set of values for four of them. Pass them explicitly on the kernel_workflow launch, and check them at G0 before anything is dispatched:

Run this port at `mode: optimize`. Author mode writes a fresh seed that replaces the source — which would overwrite the very kernel being transcribed, since the port needs that kernel's own .ttgir. So mode is not what carries the port's shape; the four args above are. A run that does not pass them behaves exactly as it always has. The commit gate is untouched by all of this and still requires beating the cumulative best by min_improve, so a sub-baseline candidate can be tracked but can never be banked.

The whole launch, with the two measured values at their opening guesses — replace both once you have numbers, per Set two of the four from measurement rather than taste below:

Workflow({
  scriptPath: "<REPO>/kernel_workflow/kernel_workflow.js",
  args: {
    kernel_path: "<TASK_DIR>",
    workflow_dir: "<REPO>/kernel_workflow",
    mode: "optimize",              // NOT author — author would overwrite the source being transcribed
    target_language: "gluon",
    use_expert_skills: "true",     // this skill is injected only when this is on
    budget: 20,
    max_no_improve: 6,             // measured on pa_decode; 4 ends one round before the payoff
    candidate_floor: 0.5,          // opening guess — reset from the debt parity_gate.py reports
    progress_delta: -0.05,
    gpu_ids: "0",
  },
})

Steer the round toward a single `deep_explore` direction rather than a specialist fan-out, for the reasons in the paragraph above this one — the harness has no way to infer that from the args, so say it in task.

In kernel_workflow terms this is the `deep_explore` track, not a set of specialist directions: it runs alone in its own round, carries its own long measure→self-profile→rewrite loop, and has authority over kernel plus wrapper — which is the shape steps 1–4 need. One mismatch to steer around: that track is documented as a minimally-steered ground-up rewrite, and here the opening is the opposite. Do not let a ground-up rewrite replace the transcription — the transcription is the anchor every later number is attributed against.

What is actually invariant, and what is only the default route. Three things are not negotiable, because each one makes the run's numbers unfalsifiable rather than merely worse: the layout equivalence gate at the end of step 1 (a numerically-correct wrong-layout anchor poisons every later delta); not mixing transcription with optimization in the same edit (it destroys the ability to attribute anything); and the comparator staying frozen for the duration. Everything else — the order the residual's owners are worked in, whether the pipeline layer is entered at all, which of two loop bodies ships — is a route chosen from measurement, and step 2a exists precisely to choose it. Read the numbered steps as the order that wastes fewest cycles on a typical port, not as a checklist to satisfy: plenty of kernels owe no pipeline debt at all, so for those the correct action at step 2 is to establish that and move on.

Two directions not to spend while the port is landing: a second arm on the transcription (above), and anything that re-tunes the plain comparator — that moves the denominator underneath a port whose whole definition is a ratio to it. Re-tune plain before the track starts or after it ends, never during.

Process stays with GEAK, with three exceptions this skill does own. It still carries no round loop, no budget model, no bound-class model and no escalation gate — run your normal kernel_workflow / e2e_workflow loop, and note that step 4's list is not a lever catalogue either: it is scoped to what this port newly made expressible, and it ranks rather than decides. What this file does own, because getting them wrong silently invalidates the port: the track shape just above; what must and must not be measured before step 1 (## Procedure preamble); and the duty to re-verify a positive (## Do-no-harm notes), which matters most in exactly the single-track setup above, because that is where the workflow's own independent re-benchmark may not be there to do it for you.

Do not use it to decide whether Gluon is the right direction. Short version: Gluon pays only when the residual is layout-shaped, because LDS swizzle/padding choice and LDS dedup are the two things plain Triton has no syntax for.

Lazy-loading contract. Read this file plus `reference.md`. Everything under `references/` is lazy — 17 files, ~3.8 k lines, load one only when you reach for the construct it documents.

Arch dispatch: gfx942 (CDNA3) vs gfx950 (CDNA4)

match.gens claims both, and the mechanics below are shared: the passes, the three re-injection conditions, the landing tells, the recover→apply→verify order. What is not shared is this table, and every row of it can change a verdict rather than a magnitude. Read it once, here, before trusting a figure or asserting a digest across generations — the rest of this file assumes you have.

Numbers live in [`references/hardware/hw_constants.json`](references/hardware/hw_constants.json), not in prose. It is the per-arch SSOT the occupancy probe already reads, so take the value from the named key and pass --arch everywhere rather than carrying a figure across a generation. A divisor that is right for one gen is a confidently wrong verdict on the other, not a rounding error.