## Summary
Align `workloads/ops/` file naming and directory structure 1:1 with the
post-#928 `tileops/ops/` layout. Pure file-move/rename refactor — no
workload logic changes.
- Drop `_fwd` suffix from mamba, attention, deltanet, and gated_deltanet
workloads
- Rename `mean_pooling_ops.py` to `mean_pooling.py`
- Move attention workloads into `workloads/ops/attention/` subpackage
- Update all imports across the repo
Closes#931
## Test plan
- [x] **AC-1**: All `from workloads.ops.<name>` imports updated for
moved/renamed files — verified by importing all 20 renamed/moved
workload classes and grep confirming zero old import paths remain
- [x] **AC-2**: `python -c "from workloads.ops.attention import ..."`
resolves for all 15 moved attention workload classes
- [x] **AC-3**: Full test suite passes — 2361 passed, 22 skipped, 0
failed (233.76s at commit 4dc54b7)
- [x] **AC-4**: No orphaned files remain after migration — all 11 old
filenames confirmed absent; `mhc_post.py`, `mhc_pre.py` at
`workloads/ops/` root; `nsa_utils.py` at `workloads/` root
## Follow-up
No follow-up issues or suggestions.
---------
Co-authored-by: Ibuki 🍃 — a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
Upgrade the benchmark workload interface from hard-coded `WorkloadBase`
composition to capability-based protocols.
Closes#918
### Changes
- **Capability protocols**: `ShapeDtypeWorkload`,
`InputGeneratingWorkload`, `BenchmarkWorkload` — structural types for
workload capabilities
- **Generic `BenchmarkBase[W]`**: base class parameterized by workload
type, replacing the hard-coded `WorkloadBase` constructor
- **`ManifestBenchmark(BenchmarkBase[ShapeDtypeWorkload])`**: aligned
contracts, zero `type: ignore` in `benchmarks/benchmark.py`
- **`WorkloadBase` preserved**: default in-repo implementation, not the
public contract
- **Docs updated**: `docs/testing.md`, `docs/trust-model.md`,
`docs/architecture.md`
- **7 tests**: duck-typed protocols, ManifestBenchmark contract,
WorkloadBase compatibility
## Test plan
- [x] **AC-1**: `roofline_vars` parameter typed to require `shape` and
`dtype` via `ShapeDtypeWorkload` protocol
- [x] **AC-2**: 1056 benchmarks collect, 103 benchmark ops pass (1
pre-existing failure in bench_argreduce, unmodified on this branch), 7
protocol tests pass
- [x] **AC-3**: No new type errors — zero `type: ignore[arg-type]` in
`benchmarks/benchmark.py`
## Verification evidence
All acceptance criteria verified by automated reviewer (two-pass code
review complete). Design direction confirmed by Ibuki-wind (Option B:
full benchmark interface refactor).
## Follow-up
- #936 — Add benchmarks/tests/ to pytest testpaths for CI coverage
- #937 — Migrate 97 BenchmarkBase subclasses to explicit generic
parameterization (depends on #936)
- #938 — Archive benchmark-workload-interface.md plan document
Suggestions: Update RooflineWorkload backward-compat alias removal once
confirmed no external consumers depend on it
---------
Co-authored-by: Ibuki 🍃 — a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
- **kernel_map design** (`docs/ops-design.md`, `docs/manifest.md`):
Define kernel_map as the Op→Kernel dispatch registration table. The
manifest declares which Kernels an Op uses so agents know what to
implement; dispatch strategy is a runtime concern not described in the
manifest.
- **trust-model update** (`docs/trust-model.md`): Add kernel_map to
manifest OWNS, clarify MUST NOT boundary (kernel internals + dispatch
strategy, not class-name registrations).
- **manifest.md restructuring**: Move `ref_api` under Entry Structure,
make `status` required, define `family` as closed set of 12 operator
families, rename `norm`→`normalization` and `conv`→`convolution`.
- **manifest + test sync**: Rename family values in `ops_manifest.yaml`
and `test_validate_manifest.py`.
- **testing.md fixes**: Update stale class names
(`MultiHeadAttentionFwdOp` → `MhaFwdOp`, `MhaFwdWorkload` →
`MhaFwdTest`), add missing imports.
- **ops-design.md cleanup**: Remove verbose Reduction-specific note, add
Kernel Dispatch section.
## Changed files
- `docs/ops-design.md` — new Kernel Dispatch section, note removal
- `docs/manifest.md` — `kernel_map` field, `ref_api` moved, `status`
required, `family` closed set
- `docs/testing.md` — stale class names and missing imports
- `docs/trust-model.md` — kernel_map in manifest OWNS, clarify MUST NOT
- `tileops/ops_manifest.yaml` — family renames (norm→normalization,
conv→convolution)
- `tests/test_validate_manifest.py` — family rename in fixtures
- `.claude/domain-rules/ops-design.md` — kernel_map rule
- `.claude/domain-rules/manifest-spec.md` — kernel_map rule, status
required
## Test plan
- [x] Pre-commit hooks pass (mdformat, codespell, ruff)
- [x] `pytest tests/test_validate_manifest.py
tests/test_ops_manifest.py` — 99 passed, 1 xfailed
- [x] No stale class names remain in design docs
Closes#876
## Follow-up
- #885 — Rewrite ops-design.md (class hierarchy doesn't match reality)
- #886 — Enforce status required and add kernel_map validator support
- #887 — Populate kernel_map for all implemented ops (depends on #886)
Suggestions:
- testing.md examples use `MhaFwdOp` — rename to
`MultiHeadAttentionFwdOp` when the code rename PR for #880 lands
- PascalCase dispatch keys in GLA/DeltaNet ops — migrate to snake_case
in a future cleanup
---------
Co-authored-by: Ibuki 🍃 — a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
Update all design documents and domain-rules files to reflect the
post-#860 naming convention: PascalCase manifest keys as canonical
identity, `ref_api` field, simplified validator (direct equality check,
no heuristic resolution), and `{PascalCaseName}{Direction}Op` naming
format.
Closes#867
## Changed files
- `docs/manifest.md` — document PascalCase key format, `ref_api` field
spec, updated examples
- `docs/ops-design.md` — naming conventions section for Op/Kernel
classes and abbreviation policy (D4)
- `.claude/domain-rules/manifest-spec.md` — align agent-facing manifest
rules with new key format
- `.claude/domain-rules/manifest-validator.md` — describe direct
equality check, remove heuristic resolution docs
- `.claude/domain-rules/ops-design.md` — reflect new naming format and
kernel naming convention (D5)
## Test plan
- [x] **AC-1**: docs/manifest.md documents PascalCase manifest keys and
the ref_api field (required, "none" when no external counterpart)
- [x] **AC-2**: docs/ops-design.md reflects the
{PascalCaseName}{Direction}Op naming format and abbreviation policy (D4)
- [x] **AC-3**: .claude/domain-rules/manifest-spec.md updated for new
key format and ref_api
- [x] **AC-4**: .claude/domain-rules/manifest-validator.md describes
direct equality check instead of heuristic resolution
- [x] **AC-5**: No stale snake_case manifest key examples remain in any
design doc
- [x] **AC-6**: Modified files pass existing tests (81/81 passed, 0
failed)
## Follow-up
No follow-up issues or suggestions.
---------
Co-authored-by: Ibuki -- a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
Clarify \`same_as(ref)\` as a dtype-only identity constraint in manifest
spec, and add validator enforcement.
**Docs:**
- \`docs/manifest.md\`: R3/R3a define \`same_as(ref)\` as exact dtype
identity (not "dependent types"). R5/R8 clarify \`same_as\` is
dtype-only — shape must be explicitly declared. R13 status default
changed to \`spec-only\`. Overall doc reduced by ~27% (470→342 lines).
- \`.claude/domain-rules/manifest-spec.md\`: matching updates —
\`same_as\` dtype identity, shape explicit, status default
\`spec-only\`.
**Validator:**
- \`_check_dtype_combos_same_as_identity()\`: enforces that
\`dtype_combos\` entries assign the same dtype to \`same_as\`-bound
tensors. Rejects partial combos where a bound tensor appears without its
reference.
- \`_is_spec_only()\`: defaults to \`spec-only\` when \`status\` is
absent, matching R13.
**Tests:** 5 new test cases — dtype_combos pass, mismatch, multi-binding
mismatch, partial-combo rejection, missing-status default.
Closes#863
## Changes
- \`docs/manifest.md\` — rewritten: concise, no "dependent types",
\`same_as\` dtype-only, status default spec-only
- \`.claude/domain-rules/manifest-spec.md\` — matching rule updates
- \`scripts/validate_manifest.py\` — \`_build_same_as_map()\`,
\`_check_dtype_combos_same_as_identity()\`, \`_is_spec_only()\` default
fix
- \`tests/test_validate_manifest.py\` — 5 new tests (81 total, all pass)
## Test plan
- [x] AC-1: \`docs/manifest.md\` R3/R3a explicitly defines
\`same_as(ref)\` as dtype identity constraint
- [x] AC-2: Validator flags \`dtype_combos\` with mismatched or partial
\`same_as\`-bound entries
- [x] AC-3: Full manifest validation passes (\`python
scripts/validate_manifest.py\` → 0 errors)
## Follow-up
No follow-up issues or suggestions.
---------
Co-authored-by: Ibuki 🍃 — a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
Extract `_ReduceOpBase` with shared `__init__` params and a unified
`_prepare_input()` / `_reshape_output()` flow, so `_SimpleReduceOp` and
`_WelfordReduceOp` inherit common validation, transpose, reshape, and
padding logic instead of duplicating it. This makes future forward-path
changes (e.g., multi-dim support) a single-point edit.
Closes#805
## Test plan
- [x] AC-1: All existing reduction tests pass (test_reduce,
test_argreduce, test_logical_reduce, test_vector_norm) — 409 passed
- [x] AC-2: No duplicated validation/transpose/reshape blocks across the
two base classes — all logic centralized in `_ReduceOpBase`
- [x] AC-3: Benchmarks still pass — 43 passed (bench_reduce,
bench_argreduce, bench_logical_reduce, bench_vector_norm)
## Benchmark
bench_reduce.py, bench_argreduce.py, bench_logical_reduce.py,
bench_vector_norm.py: 43 passed, 0 failed
## Follow-up
- #831 — Evaluate migrating remaining reduction ops (argmax, argmin,
any, all, norms, logsumexp, count_nonzero) to `_ReduceOpBase`
No pending suggestions (previous `StdOp`/`VarOp` forward dedup
suggestion adopted in d311995).
---------
Co-authored-by: Ibuki 🍃 — a wind born from Claude Opus <Ibuki-wind@users.noreply.github.com>
## Summary
- Fix trust-model.md pipeline order: `Manifest → Test → Implementation →
Benchmark` (was incorrectly `Manifest → Implementation → Test →
Benchmark`)
- Remove issue number reference from design doc (design docs should not
contain issue numbers)
- Delete `docs/workflow.md` — redundant with trust-model.md pipeline +
domain rules + conventions/types.sh
- Clean all references to workflow.md in CLAUDE.md, README.md,
trust-model.md
## Test plan
- [x] `rg workflow.md` returns no matches outside worktrees
- [x] trust-model.md pipeline matches the discussed design: manifest
first, then test, then implementation, then benchmark
- [x] No issue numbers in design docs
- [x] `pre-commit run --all-files` passes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- New `docs/trust-model.md` — four-stage pipeline trust boundaries
(manifest → implementation → test → benchmark) and workloads layer
contract
- Added `## Boundary` sections (OWNS / MUST NOT modify / MAY READ) to
all 4 domain rule files
- Added "Writing a Test" and "Writing a Benchmark" operation guides to
`docs/testing.md`
- Rewrote top-level Test/Benchmark Pattern example to match post-PR#787
three-file architecture
- Fixed outdated class descriptions, directory structure, aspirational
claims, and internal contradictions
Resolves#790. Related: #787, #789.
## Key design decisions
1. **workloads/ is not a development stage** — shared input-definition
layer. Test stage OWNS it (QA creates workload classes first from
manifest).
2. **Implementation MAY READ tests/, MUST NOT MODIFY** — developer reads
ref_program for behavior understanding; modifying the correctness oracle
is the unacceptable cheat.
3. **Benchmark-local baselines allowed** — benchmarks must not import
oracle/ref from tests/ or workloads/, but may define local baseline
functions.
4. **Operation guides in testing.md, principles in trust-model.md** —
explicit bidirectional cross-references between all documents.
## Changes (10 files, +216 / -40)
| File | Change |
|------|--------|
| `docs/trust-model.md` (new) | Pipeline boundaries, per-stage OWNS/MUST
NOT/MAY READ, workloads contract |
| `docs/testing.md` | Rewrote example to three-file pattern, added
Writing a Test/Benchmark guides, fixed class table |
| `docs/architecture.md` | Added `workloads/` to directory tree + module
table (labeled "shared layer, not a module") |
| `docs/ops-design.md` | Trust boundary cross-ref, removed aspirational
"target architecture" label |
| `docs/workflow.md` | Fixed Step 2 to not claim implementer writes
tests, added trust-model back-link |
| `.claude/domain-rules/benchmark.md` | Boundary header with file-path
MUST NOT, fixed record()/calculate rules |
| `.claude/domain-rules/testing-budget.md` | Boundary header, OWNS
tests/ + workloads/ |
| `.claude/domain-rules/ops-design.md` | Boundary header, MAY READ
tests/ with rationale |
| `.claude/domain-rules/manifest-spec.md` | Boundary header |
| `CLAUDE.md` | Added `workloads/` row to domain rules table |
## Test plan
- [x] All cross-references bidirectional (every forward ref has matching
back ref)
- [x] Top-level example matches "Writing a Benchmark" checklist (one
consistent pattern)
- [x] No internal contradictions between trust-model.md, testing.md,
domain rules, and workflow.md
- [x] All API descriptions verified against actual code
- [x] No aspirational claims in modified documents
- [x] `pre-commit run --all-files` passes
- [x] Documentation-only PR — no code changes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Make L1 validator strictly require that all manifest-declared params for
`status: implemented` ops appear in the Op's `__init__()` + `forward()`
union signature. This ensures manifest declarations stay in sync with
actual code interfaces.
- Update `check_l1_signature()` to inspect both `__init__` and `forward`
param names
- Audit and fix all 23 implemented ops that failed strict L1
- Update `docs/manifest.md` L1 description to reflect the stricter rule
Closes#765
## Test plan
- [x] **AC-1**: check_l1_signature() checks manifest params against
__init__ + forward union, not just forward
- [x] **AC-2**: All status: implemented ops pass strict L1 in CI
- [x] **AC-3**: docs/manifest.md L1 description updated to reflect
strict matching rule
- [x] **AC-4**: Modified files pass existing tests
**Test results**: 47/47 passed (24 validator + 23 manifest), 0 failed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes#759
## Summary
- Add R16-R18: signature variant rules — no `Optional[Tensor]` in
manifest, ops with conditional inputs split into variant entries linked
by `variant_of`
- Add R19: tensor layout declaration — contiguous row-major default,
optional `layout` field for spatial ops
- Restructure manifest.md: Rules (R1-R19) promoted to top-level section,
Entry Structure subsections ordered to match field table, remove
outdated Tier Model
- Add Class Hierarchy diagram to ops-design.md
- Move domain rules from `.claude/rules/` to `.claude/domain-rules/`
(on-demand loading via CLAUDE.md table)
- Add `.claude/domain-rules/manifest-spec.md` with R1-R19 condensed
agent rules
## Test plan
- [x] pre-commit passed
- [x] No code changes — docs and config only
## Additional context
Design-only PR. Implementation follow-ups:
- #741: upgrade reduction/scan ops to match manifest spec + NormBase
refactor
- #765: tighten L1 validator to check full param coverage
- MoE entry splitting (fused_moe, fused_topk variants) — separate PR
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Define a unit-test policy for operator tests and provide a local script
(`scripts/test_node_delta.py`) that reports test node count delta for
touched files in a PR, making growth visible and justifiable.
Closes#760
## Changes
**M1 — Unit-test policy**
- Added Unit-Test Policy section to `docs/testing.md` covering: allowed
UT purposes, dtype risk class rule, shape coverage rule, manifest
separation, growth justification
- Added `.claude/rules/testing-budget.md` with concise agent-enforceable
version
- Verified policy is consistent with existing smoke/full tier system in
`tests/conftest.py`
**M2 — Growth-detection script**
- Created `scripts/test_node_delta.py` that compares test node counts
between current branch and main
- Added usage instructions to `docs/testing.md`
- Added note in `.claude/rules/testing-budget.md` about running script
and justifying growth
## Test plan
- [x] **AC-1-1**: docs/testing.md contains a Unit-Test Policy section
with dtype risk class, shape coverage, manifest separation, and growth
justification rules
- [x] **AC-1-2**: .claude/rules/testing-budget.md exists and is loadable
by Claude Code
- [x] **AC-1-3**: Policy does not contradict existing tier enforcement
in tests/conftest.py
- [x] **AC-2-1**: Script runs successfully on the current repo and
reports node counts for at least 3 existing test files
- [x] **AC-2-2**: Script correctly detects delta when a test file has
more nodes than its main branch version
- [x] **AC-2-3**: Script exits 0 regardless of delta (non-blocking)
- [x] **AC-2-4**: Script handles new test files (no main branch version)
without error
- [x] **AC-2-5**: docs/testing.md documents how to run the script
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Revise `docs/manifest.md` into a complete, unambiguous spec that an
agent can follow to write correct manifest entries, generate
Op.forward() / Op.infer_shape(), and produce validators and test
generators.
Key changes:
- R1: ordered-dict semantics with insertion-order constraint
- R4: Cartesian-product vs explicit dtype_combos semantics
- R13: status field with spec/implemented gating rule
- R14: roofline vars binding mechanism with evaluation context and 4
case examples
- R15: PyTorch interface alignment rule
- Add scan family to Tier 1 table
- All examples use dict format for params; reduce examples include
keepdim
Closes#743
## Test plan
- [x] **AC-1**: R1 updated to ordered-dict with implementation
constraint and agent rule documented — pass
- [x] **AC-2**: status field added to Entry Structure with R13 gating
rule — pass
- [x] **AC-3**: R14 roofline vars mechanism with evaluation context and
4 case examples — pass
- [x] **AC-4**: Reduce example in manifest.md includes keepdim; softmax
exception noted — pass
- [x] **AC-5**: R15 PyTorch interface alignment rule added — pass
- [x] **AC-6**: scan family added to Tier Model table — pass
- [x] **AC-7**: R4 revised with Cartesian-product-vs-explicit semantics
— pass
- [x] **AC-8**: All examples in manifest.md use dict format for params
(no residual list format) — pass
- [x] **AC-9**: Modified files pass existing tests — pass
Tests: 19/19 passed
---
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes#738
## Summary
- Add `scripts/validate_manifest.py` implementing manifest validation
for schema, `Op.forward()` signature consistency, `shape_rules` syntax,
dtype conformance, and benchmark manifest usage
- Integrate the validator into the preflight workflow with a dedicated
`validate-manifest` job
- Add MoE manifest entries and migrate the MoE benchmarks in this PR to
manifest-driven workloads via `load_workloads()` and `eval_roofline()`
- Make benchmark strictness explicit with `source.bench_manifest_driven:
true` for migrated entries, while leaving legacy non-migrated benchmarks
as warnings
- Clarify in `docs/manifest.md` that `workloads` are for
nightly/performance benchmark coverage only, not unit-test coverage
- Add merge-ready validator coverage in
`tests/test_validate_manifest.py`
- Add a developer-agent rule in `.claude/rules/manifest-validator.md`
forbidding validator edits as a way to bypass manifest constraints
## Test plan
- [x] pre-commit passed (all hooks green)
- [x] `pytest -q tests/test_validate_manifest.py` -- 20 passed
- [x] `pytest -q tests/ops/test_moe_permute.py` -- 9 passed
- [x] `python scripts/validate_manifest.py` passes on current codebase
(exit 0)
## Structural Readiness
SKIP -- primary deliverable is infrastructure (manifest validator + CI
integration), not a new kernel/op.
## Additional context
**Validation checks:**
- **Schema**: YAML structure, required fields, and field types
- **Signature**: `Op.forward()` parameters must match manifest inputs,
plus any accepted manifest-declared runtime params, in order
- **Shape**: `shape_rules` must parse as valid Python expressions
- **Dtype**: manifest dtype strings and workload dtypes must be
recognized
- **Benchmark**: migrated benchmark files must import and call
`load_workloads` / `eval_roofline` with the correct op name
**Current enforcement model:**
- `status: spec-only` entries receive schema-only validation
- L4 benchmark enforcement is hard-fail only for entries that explicitly
opt in with `source.bench_manifest_driven: true`
- Legacy benchmark files that have not yet migrated remain warnings, not
CI failures
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Restructure architecture.md from static module topology to four
color-coded data flows: Op Delivery, Perf Tuning, HW Calibration,
Publish
- Add flow status table showing done/broken/partial/not-started per
pipeline with specific gaps
- Highlight kernel tuning loop (M2→M4→M5→M2) as a visual subgraph — the
system's core challenge
- Rename M4 from Benchmark to Perf Tuning; broaden M8 to include design
docs
- Merge CI Guard into parent flows (M3→M7 is Op Delivery, not a separate
flow)
- Align all sections (module reference, data contracts, agent production
loop, documentation system) with diagram changes
## Test plan
- [x] pre-commit passed
- [x] mermaid renders correctly on GitHub
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Closes#704
## Summary
- Add `tileops/manifest.py` with `load_workloads()` and
`eval_roofline()` functions that make `ops_manifest.yaml` a live,
code-consumed data source
- Populate all 10 norm-family ops in the manifest with dict-format
signatures (inputs/outputs as dicts, not lists), LLM-representative
workloads, and roofline formulas
- Rewrite all 8 norm benchmark files to derive shapes from
`load_workloads()` and compute flops/memory via `eval_roofline()` — no
hardcoded shapes or formulas remain
- Update schema tests to validate the new dict-based signature format
## Structural Readiness
PR does not introduce or modify kernel/op implementation code. All
changes are manifest infrastructure and benchmark data-source wiring. Op
readiness checklist items are not applicable.
Verified benchmark-side checklist items relevant to this diff:
- Benchmark files exist and inherit `BenchmarkBase`
- `calculate_flops()` and `calculate_memory()` return non-None via
`eval_roofline()`
- `BenchmarkReport.record()` uses Op objects as first argument
- All benchmarks include torch-family baselines
## Test plan
- [x] AC-1: `pytest -q tests/test_ops_manifest.py` passes (8 tests)
- [x] AC-2: `load_workloads()` and `eval_roofline()` correctly read from
`ops_manifest.yaml`
- [x] AC-3: Manifest contains 10 norm ops with dict-format signatures,
all source paths valid
- [x] AC-4: All 8 norm bench files use manifest API — no hardcoded
shapes or formulas
- [x] AC-5: `pytest --collect-only` shows manifest-derived test IDs with
model-architecture labels (61 cases)
- [x] AC-6: Schema tests pass with dict-format validation
- [x] AC-7: Manifest YAML header documents the dict-format schema
```bash
# Validation commands
python -m pytest -q tests/test_ops_manifest.py
python -m pytest --collect-only -q benchmarks/ops/bench_{rms_norm,layer_norm,batch_norm,group_norm,instance_norm,ada_layer_norm,fused_add_layer_norm,fused_add_rmsnorm}.py
```
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Restructure `docs/manifest.md` as a spec-driven, agent-friendly
reference:
- Signature uses list style (preserves positional order)
- Shape system: fixed rank (`shape` present) vs arbitrary rank (`shape`
absent), with `same_as(ref)`, `constraints`, and `shape_rules`
- `shape_rules` are the source of truth for generating
`Op.infer_shape()` — no fallback
- `dtype_combos` for mixed-precision ops with restricted combinations
- Decision tree (declare shape → generate `infer_shape()`) with rule
references
- Compact R1-R12 rule labels, field tables, flow-style YAML examples
- Align `ops_manifest.yaml` (`rmsnorm_fwd`) with the new spec
- Add 5 schema validation tests for the manifest
## Test plan
- [x] `pytest tests/test_ops_manifest.py -v` — 13 tests pass
- [ ] Review `docs/manifest.md` for clarity and completeness
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
Add HBM bandwidth microbenchmark for GPU hardware characterization (M6
module).
- `benchmarks/hardware/memory/hbm_bandwidth.py` — measures
read/write/copy bandwidth across sizes and dtypes, computes calibration
factor against theoretical peak
- Reads theoretical specs directly from `tileops/perf/profiles/` via
`load_profile()` (single source of truth)
- `benchmarks/hardware/utils/bench.py` — thin wrapper around
`tilelang.profiler.do_bench` with bandwidth calculator
- `docs/roofline.md` — relax "zero external dependencies" to "no
third-party dependencies beyond the project itself"
No CSV output, no env.py, no global state — minimal code focused on
producing the `hbm.calibration` value for GPU profiles.
## Test plan
- [ ] `python -c "import ast;
ast.parse(open('benchmarks/hardware/memory/hbm_bandwidth.py').read())"`
— syntax OK
- [ ] Run `python benchmarks/hardware/memory/hbm_bandwidth.py` on H200 —
verify theoretical from profile, measured peak, and calibration factor
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Replace undocumented Data Flow diagram with **Data Contracts** section
— explicit table recording every inter-module artifact, format, and
direction
- Module graph: `LR` → `TD` layout with `subgraph` grouping and labeled
edges for readability
- Clarify M4 as performance regression guard, M6 as offline calibration,
M7→M8 as CI-scheduled perf tables update
- Reorder sections: Modules → Data Contracts → Two-Layer Separation (M2)
- Note M3/M4 have no data dependency (process convention only)
## Test plan
- [ ] Verify mermaid diagram renders correctly on GitHub
- [ ] Verify Data Contracts table matches module graph edges 1:1
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes#627
## Summary
- Create `ops_manifest.yaml` at repo root as the spec-driven op
registry, establishing the schema for all future op definitions.
- Register `rmsnorm_fwd` as the first entry with all four required
fields: `signature`, `workloads`, `roofline`, and `source`.
- Workloads cover Llama-3.1-8B (hidden=4096), 70B (hidden=8192), and
405B (hidden=16384) with both prefill (seq_len=2048) and decode
(seq_len=1) shapes.
- Add validation test suite (`tests/test_ops_manifest.py`) with 16 tests
covering schema structure, field presence, source path existence, and
workload completeness.
## Test plan
- [x] `python -m pytest tests/test_ops_manifest.py` -- 16/16 pass
- [x] All source file paths in manifest resolve to existing files
- [x] YAML is valid and parseable
- [x] Workload dimensions match Llama-3.1 model specs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Add `docs/perf/` directory with structured performance documentation
for elementwise kernels
- **Checklist** (`elementwise.md`, ~25 lines): heuristic rules for
agent/reviewer audit covering strategy selection, vectorization, config
tuning, caching, and code quality
- **Evidence** (`elementwise-evidence.md`): measured data and reasoning
from PRs #500, #537, #538, #539 — loaded on demand only when
justification is needed
- **Index** (`README.md`): test environment table (H200/CUDA
12.8/TileLang 0.1.8) scoping all conclusions, plus category index for
future op families
- Checklist framed as heuristics with explicit guidance: violations need
justification, not mandatory fixes
## Test plan
- [x] All markdown files pass mdformat and codespell pre-commit hooks
- [x] Cross-links between checklist, evidence, and README verified
- [x] No runtime code changes
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Remove 5 domain-knowledge skills (`migrating-new-op`, `tune`,
`tune-multiplication`, `check-kernel-format`, `kernel-debug`) whose
content has been migrated to the [project
wiki](https://github.com/tile-ai/TileOPs/wiki)
- Add `op-compliance-checklist.md` to the `creating-pull-request` skill
as an on-demand Step 2 HARD GATE — agent reads and verifies kernel/op
structural conventions only when the PR touches kernel/op code
- Delete `docs/kernel-op-conventions.md` (content consolidated into
wiki)
- Update `CLAUDE.md` skill index to remove deleted skill entries
## Test plan
- [x] `pre-commit run --all-files` passed
- [x] Verified remaining skills (`committing-changes`,
`creating-pull-request`, `creating-issue`, `lifecycle-pull-request`,
`lifecycle-issue-fixer`) are unaffected
- [x] Confirmed `op-compliance-checklist.md` is correctly referenced
from `SKILL.md` Step 2
- [x] Confirmed PR template is unchanged from main
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Summary
- Refactored `lifecycle-pull-request` SKILL.md to use explicit `Skill`
tool invocations instead of inline step repetition, decomposing the PR
flow into discrete, reusable skill calls
- Fixed review issues in the PR lifecycle skill: `validate.sh` bug,
timeout typo, and worktree detection logic
- Created `.claude/conventions/types.sh` as a single source of truth for
all type lists, regex patterns, and label mappings; updated all
validation scripts, CI workflows, SKILL docs, and `CONTRIBUTING.md` to
source it, eliminating type drift across 11+ files
- Removed legacy type aliases (`Feature`, `Docs`, `Build`, `Style`,
`Lint`) that had accumulated across files
- Synced repo labels to match canonical set (added `bench`, `test`,
`perf`)
- Fixed pre-commit autofix message wording
## Test plan
- [x] `source .claude/conventions/types.sh` renders correct regex
patterns
- [x] `validate.sh` scripts pass with patterns sourced from `types.sh`
- [x] CI workflows reference `types.sh` instead of hardcoded patterns
- [x] Legacy types (`Feature`, `Docs`, `Build`, `Style`, `Lint`) are
correctly rejected by validation
- [x] Repo labels (`bench`, `test`, `perf`) created and synced to
canonical mapping
- [x] pre-commit passed
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
- Remove L3 (`tileops/functions/`, `tests/functions/`) and L4
(`tileops/layers/`, `tests/layers/`) directories — simplify from 4-layer
to 2-layer architecture (L1 Kernel + L2 Op)
- Remove cross-layer `test_grouped_gemm_complete` test that imported
from `tileops.functions`
- Update all documentation (DEVELOPMENT.md, README.md, Claude.md, issue
templates, SKILL.md) to reflect 2-layer architecture
## Test plan
- [x] `ruff check` passes on modified Python files
- [x] No remaining imports of `tileops.functions` or `tileops.layers`
(verified via grep)
- [x] `import tileops` works correctly, exports `["ops"]`
- [x] CI lint/test pass
Closes#193🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
**Docs & config consistency fixes:**
- Rename CI workflow from `hello-self-hosted` to `CI`
- Mark mypy strict checking as *(planned)* in DEVELOPMENT.md — it is not
yet implemented (no config, no dependency, no CI job)
- Remove `ANN` from ruff lint select — every ANN sub-rule was
individually ignored, making it a no-op
- Fix README: `tilelang >= 0.1.8` → `== 0.1.8` to match the pinned
version in `pyproject.toml`
- Fix README: acknowledge `einops` in the "Lightweight Dependencies"
claim
- Clean `.gitignore`: remove unrelated legacy entries (nnfusion,
VisualGDB, docbuild artifacts, precompiled headers, etc.), restore
`!testing/python/debug` exception
- Fix `Claude.md`: replace reference to non-existent `conda activate
top` with generic venv instruction
**Claude Code skill & config fixes:**
- Move custom skills from `.claude/<name>/` to `.claude/skills/<name>/`
so they are auto-discovered as user-invocable (fixes
`/creating-pull-request` and `/migrating-new-op` not appearing in skill
list)
- Add `.claude/settings.json` enabling `superpowers` plugin for the
project
Relates to #221, #222
## Test plan
- [ ] Verify `pre-commit run --all-files` passes (lint-only changes)
- [ ] Verify `python -m build` still produces sdist + wheel correctly
- [ ] Verify `/creating-pull-request` and `/migrating-new-op` skills are
discoverable in a new Claude Code session
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
## Summary
Closes#186
- Rename `top/` → `tileops/` to align the source directory name with the
package name defined in `pyproject.toml` (`name = "tileops"`)
- Update all internal imports (`from top.` → `from tileops.`) across 116
Python files
- Update documentation paths in `DEVELOPMENT.md`, `README.md`,
`SKILL.md`, and issue templates
- Update `.pre-commit-config.yaml` yapf workaround path
## Motivation
The package is named `tileops` in `pyproject.toml`, but the source code
previously lived under `top/`. This creates a mismatch between the
package name and the module import path, which is confusing for
contributors and downstream users.
## Test plan
- [x] `pre-commit run --all-files` passed
- [x] `PYTHONPATH="$PWD" python -m pytest tests/ops/test_mha.py` — 6
passed
- [x] `PYTHONPATH="$PWD" python -m pytest tests/ops/test_gemm.py
tests/ops/test_gqa.py tests/functions/test_mha_func.py` — all passed
- [x] `import tileops` works correctly
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Closes#176
## Summary
- Fix `ZeroDivisionError` by falling back to `event` backend when
`cupti` returns zero latency
- Root cause: CUPTI profiler can fail to capture kernel events in
certain environments (e.g. Nsight Compute exclusively holds CUPTI),
causing `do_bench` to return 0
- Fix: when cupti returns `<= 0`, automatically retry with `event`-based
timing which uses `cuda.Event` and does not depend on CUPTI
- Fix pytest command in `docs/DEVELOPMENT.md` to use `PYTHONPATH="$PWD"
python -m pytest`
- Deduplicate docs: `docs/DEVELOPMENT.md` (source) -> `Claude.md`
(reference) -> skill (reference)
- Add `creating-pull-request` skill with pull-before-push rule
- Fix repo path and dead reference in skill
## Related
- #184 — Separate benchmark profiling from unit tests (follow-up)
- #183 — Bandwidth unit conversion investigation (pre-existing)
## Test plan
- [x] `pre-commit run --all-files` passed
- [x] `PYTHONPATH="$PWD" python -m pytest tests/ops/test_mha.py` — 6
passed
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: ChongLi <35960466+RMLYC@users.noreply.github.com>
## Description
<!-- Briefly describe the changes introduced by this PR -->
- Fix the project directory structure description in the development
guide
- Add bug report issue template
## Type of Change
- [ ] Bug fix
- [ ] New operator implementation
- [ ] Performance improvement
- [x] Documentation update
- [ ] Infrastructure/CI
## Checklist
- [x] I have run `pre-commit run --all-files` and fixed all linting
issues.
- [x] I have verified that my changes pass local unit tests.
- [ ] **(For new ops)** I have added the corresponding `Benchmark` class
in `benchmarks/`.
- [ ] **(For new ops)** I have reported benchmark results in the
tracking issue.
This pull request enhances the project's code quality, developer
experience, and overall structural integrity. It mainly makes the
following changes:
* Introduced a new `.flake8` configuration file and updated the
`.pre-commit-config.yaml` to enable more linting and formatting hooks.
* Removed the `flash-attention` git submodule and updated `.gitignore`
and `MANIFEST.in` to streamline the project's dependencies and
packaging.
* The `pyproject.toml` file was updated to reflect the new linting
setup.
## Description
Refactor the DEVELOPMENT doc and the corresponding github template
* Documentation Refinement: The DEVELOPMENT.md guide has been updated to
streamline the 'Development Workflow' section.
* Enhanced Operator Development Workflow: The guide now includes more
detailed instructions for new operator development, such as task
decomposition for tracking issues, explicit docstring requirements for
each layer (Kernel, Op, Functional API, Layer), and a new dedicated step
for benchmark results.
* GitHub Template Updates: Minor adjustments were made to GitHub
templates; New issue template for new op subtask.
## Type of Change
- [ ] Bug fix
- [ ] New operator Implementation
- [ ] Performance improvement
- [x] Documentation update
- [ ] Infrastructure/CI
## Checklist
- [x] I have run `pre-commit run --all-files` and fixed all linting
issues.
- [x] I have verified that my changes pass local unit tests.
- [ ] **(For new ops)** I have added the corresponding `Benchmark` class
in `benchmarks/`.
- [ ] **(For new ops)** I have reported benchmark results in the
tracking issue.
This pull request refactors the project's `README.md` file. It mainly
makes the following changes:
1. The `README.md` has been refactored to
provide a more comprehensive and structured overview of the TileOPs
project, including detailed feature descriptions and design principles.
2. A new project logo has been added to the
`README.md` for improved branding and visual appeal.
Cao Ying