feat(forge): pass task identity and workload metadata to forge-loop

.github/workflows/perf-helpers.yml

@@ -12,4 +12,6 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+      - run: python -m pip install "pytest>=8,<10" "PyYAML>=6,<7"
       - run: make check-perf-helpers
+      - run: make check-forge

Makefile

@@ -7,7 +7,7 @@
 SHELL := /bin/bash
 
 .PHONY: help docker-shell docker-check-agents docker-smoke docker-run docker-parallel-run docker-setup-flydsl docker-setup-geak \
-        check-docker-runner check-evaluator check-held-out check-visualization \
+        check-docker-runner check-evaluator check-forge check-held-out check-visualization \
         visualization-build visualization-serve visualization-run \
         sync-perf-helpers check-perf-helpers materialize-perf-workspace \
         materialize-perf-task cleanup-works install-cursor-agent vllm
@@ -30,6 +30,7 @@ help:
 	@echo "make docker-setup-geak   - Install the Claude Agent SDK when absent (for the geak_v4 agent)"
 	@echo "make check-docker-runner - Check Docker runner syntax and runtime-specific arguments"
 	@echo "make check-evaluator     - Run centralized evaluator unit tests"
+	@echo "make check-forge         - Run Forge metadata adapter unit tests"
 	@echo "make check-held-out      - Run held-out module unit tests"
 	@echo "make visualization-run   - Build and serve the local comparison dashboard"
 	@echo "make check-visualization - Run visualization module unit tests"
@@ -86,6 +87,9 @@ check-docker-runner:
 check-evaluator:
 	@python3 -m unittest discover -s tests -p 'test_evaluator_*.py'
 
+check-forge:
+	@python3 -m pytest -q tests/test_forge_framework.py tests/test_forge_kb_producer.py
+
 check-held-out:
 	@python3 -m unittest discover -s tests -p 'test_held_out.py'
 

agents/forge/README.md

@@ -0,0 +1,64 @@
+# Forge agent
+
+## Kernel identity metadata
+
+Arena runs Forge and scores the resulting kernel. Optional external knowledge
+services are owned by KernelForge; their availability or publication status does
+not decide whether Arena writes a score.
+
+Tasks may provide metadata that Arena forwards to `forge-loop`:
+
+```yaml
+kernel_identity:
+  logical_operator: unified_attention_with_output
+  kernel_kind: triton
+  source_owner: aiter
+  workload:
+    source: session_cases.json
+    primary_case: representative-case-id
+    selector_schema:
+      name: hyperloom-v1
+      fields:
+        q_tokens: QTOKENS
+        head_size: HEADSIZE
+```
+
+When `kernel_identity` is absent, Arena omits its operator and workload flags and
+lets forge-loop use its normal inference/defaults. When present, each supplied
+field is forwarded. `kernel_kind` selects the fellow used for the run; it is not
+passed as a `--kernel-kind` CLI argument and is not part of KernelForge's
+implementation signature.
+
+The source JSON must contain a non-empty `cases` list. Each case must have a
+unique `id` and a non-empty scalar `params` mapping. Tasks using session cases
+may declare a `hyperloom-v1` selector schema that maps dimensions
+Hyperloom can deterministically emit to uppercase selector keys without
+underscores. Every original parameter remains preserved in
+`session_cases.json`, while only mapped flat selectors are passed through
+`primary`/`minimal`/`validation`. Arena derives an unambiguous `shape-v2`
+workload key from canonical JSON rather than splitting dimension names on
+underscores.
+
+Inline workloads are also supported:
+
+```yaml
+kernel_identity:
+  logical_operator: rms_norm
+  kernel_kind: triton
+  source_owner: vllm
+  workload:
+    shapes:
+      primary: {M: 4096, N: 8192, dtype: bf16}
+      validation:
+        - {M: 1, N: 8192, dtype: bf16}
+```
+
+`source_file_path[0]` is the anchor implementation. Additional entries in
+`source_file_path` and the optional `editable_sources` list form one complete
+edit allowlist passed through `--source-files`. Agents may inspect other
+dependencies but must not edit files absent from that allowlist.
+`target_kernel_functions` remains the concrete symbol list; it is not a
+substitute for `logical_operator`. Keep it focused on useful edit/profile hints
+defined in the editable sources. Reuse identity is based on KernelForge's
+source-derived pristine implementation signature, so task hints do not
+need to reproduce a consumer caller's target list exactly.

agents/forge/agent_config.yaml

@@ -9,10 +9,9 @@
 model: claude-opus-4-8
 
 # Backend expertise (fellow) is INFERRED by the launcher, per task family:
-#   * repository / image_kernel tasks -> from `repository_language`
-#       hip -> hip-fellow, triton -> triton-fellow
-#       (the source repo like aiter/sglang is NOT the fellow: the aiter fellow
-#        only integrates prebuilt ops, so an aiter-repo HIP kernel uses hip)
+#   * repository / image_kernel tasks -> curated `kernel_kind` first, then
+#     `repository_language`; this keeps HIP source syntax separate from CK/FlyDSL
+#     implementation semantics.
 #   * snippet "<src>2<dst>" tasks     -> the target side picks the fellow
 #       triton2triton / instruction2triton -> triton-fellow
 #       hip2hip / cuda2hip / torch2hip      -> hip-fellow
@@ -39,8 +38,3 @@ timeout_seconds: 7200
 # Claude permission mode. acceptEdits works under root; bypassPermissions is
 # blocked by Claude Code's security policy for root.
 permission_mode: acceptEdits
-
-# NOTE: no shapes_json here on purpose. The generic adapter ignores --shape (the
-# task's own pytest owns its shapes), so passing kernel-specific n= values adds
-# no value and isn't portable across tasks. The forge-loop CLI defaults to "{}".
-# Only set shapes_json if you use a per-kernel driver that parses --shape.