@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/reasoning/hardware-microbench.md

@@ -1,116 +0,0 @@
-# Hardware Microbenchmark Protocol (skeleton)
-
-> **Version**: MVP skeleton. Companion to `api-probing.md`. Covers three
-> categories of **active** microbenchmark probes that run real kernels to
-> surface timing/throughput facts the passive introspection APIs cannot.
->
-> **Authoritative design source**: `docs/design/知识库的问题以及改进方案/方案分册/07-runtime-introspection-方案.md` §R.4.5
->
-> If this file and booklet 07 §R.4.5 disagree, booklet 07 wins.
-
-The purpose of a hardware microbenchmark is to turn *"the driver says SM count = 132"* into *"a `fma.rn.f32` costs 0.5 cycles throughput and 4 cycles latency on this exact H200, at this exact clock, with these exact drivers."* Microbench results are the primary source for any `verified.md` claim about **per-instruction cost** or **per-level memory latency**.
-
-## Three probe kinds
-
-| Kind | Purpose | MVP scope |
-| --- | --- | --- |
-| **Compute latency** | Per-instruction throughput/latency for CUDA core instructions (`fma` / `shfl` / `vote` / `ld.shared` / `ld.global` / `atom`) | **In scope**. Two data sources co-exist: (a) canonical per-instruction numbers from `kp_introspect microbench compute-latency` (pre-built CLI), (b) skill-specific probes written by the KB-gen agent for each skill following this protocol. Both land as records under `sources/experience/hw-probes/`; (a) under `sources/experience/hw-probes/canonical/`, (b) under `sources/experience/hw-probes/<instruction-slug>/`. |
-| **Memory pointer chasing** | End-to-end read latency per memory level (SMEM same-bank / SMEM full-width / L1 / L2 / HBM) | **In scope**. Same dual-source arrangement: (a) canonical curves from `kp_introspect microbench memory-latency`, (b) agent-written skill-specific probes for coalescing / bank-conflict. |
-| **Feature sweep (whitepaper-driven)** | Agent reads an architecture whitepaper, extracts a feature ledger, designs one probe per feature (TMA / DSMEM cluster sweep / wgmma / setmaxnreg) | **Deferred** — scaffolded only; execution waits for F0 source corpus + 40-hardware-feature layer. |
-
-## Shared rules
-
-Every microbench probe must obey:
-
-1. **`benchmark-protocol.md`** — warmup 5, repeat 20, CUDA events, correctness first.
-2. **`api-probing.md` Step 1** — grep upstream **before** writing any kernel.
-3. **`api-probing.md` Step 3–4** — same compile / run / record loop.
-4. **`templates/frontmatter/experience.yaml`** — same frontmatter schema.
-
-Additional microbench-specific constraints (enforced by `lint_knowledge.py`):
-
-1. **Isolate one effect**. A compute-latency probe must not be confounded by memory stalls; a memory-latency probe must not measure compute. If you cannot isolate, split into two probes.
-2. **Defeat predictors**. Pointer chasing uses randomized node order. Compute loops use `volatile` / inline `asm` to prevent dead-code elimination.
-3. **Read the clock correctly**. Prefer `%clock64` for cycle-level measurement; fall back to `cudaEventElapsedTime × observed_sm_clock_mhz` (from `kp_introspect device-dynamic`) only when `%clock64` is unreliable.
-4. **Sample ≥ 4096 per data point** — not per kernel launch. A single launch collects thousands of samples via an unrolled inner loop.
-5. **Record the clock**. Every probe records `observed_clock_mhz`; if `clock_policy: unknown` the probe is still valid but `evidence_level` stays `inferred`.
-
-## Protocol — Compute latency probe
-
-```
-Step 1. Pick the instruction (e.g. shfl.sync.bfly under warp-reduce mask).
-Step 2. Grep upstream:
-          rg 'shfl\.sync\.bfly' corpus/nvidia/cuda-official/cuda-toolkit-documentation-13.2/ptx-isa/
-Step 3. (Optional) Sanity-check against the canonical baseline:
-          kp_introspect microbench compute-latency --instructions shfl.sync.bfly --samples 4096 \
-              --output sources/experience/hw-probes/canonical/shfl-sync-bfly.json
-        Canonical data is general-purpose; the skill-specific probe below
-        exercises the exact pattern this skill uses (e.g. with a specific mask,
-        under warp-reduce order, with specific dtype).
-Step 4. Write probe .cu:
-          - kernel body = unrolled loop of 128 dependent instructions
-          - single thread, single block, minimal setup
-          - uint64_t s = clock64(); <128 insn>; uint64_t e = clock64(); out[tid] = e - s;
-          - use `volatile` / inline asm to block DCE
-Step 5. nvcc -arch=sm_90a -O3 -std=c++17 -lineinfo -o probe probe.cu
-Step 6. Run N=4096 outer trials; collect all (e - s); divide each by 128
-          → per-instruction throughput in cycles.
-Step 7. Repeat with pipeline-empty mode (single instruction between bar.sync)
-          → per-instruction latency in cycles.
-Step 8. Write the probe record to
-          sources/experience/hw-probes/<instruction-slug>/<YYYY-MM-DD>-<task-slug>.md
-        using templates/frontmatter/experience.yaml. Then in the target
-        skill.md, append a bullet under `## Measured Characteristics` that
-        links to the probe record. **Do not write to skill verified.md**
-        (dropped in MVP). **Do not embed the table inline in skill.md**
-        (the probe record is the single source of truth).
-```
-
-## Protocol — Memory pointer chasing probe
-
-```
-Step 1. Pick a level: smem-same-bank | smem-full-width | l1 | l2 | hbm
-Step 2. Pick working-set bytes so the list fits exactly this level:
-          - smem     → 32 KB - 192 KB (bounded by opt-in shmem)
-          - L1       → 24 KB - 48 KB (< L1 capacity)
-          - L2       → 40 MB (> L1, < L2 capacity)
-          - HBM      → 2 GB (> L2 capacity)
-Step 3. (Optional) Sanity-check against canonical:
-          kp_introspect microbench memory-latency --levels <level> --samples 4096 \
-              --output sources/experience/hw-probes/canonical/memory-<level>.json
-Step 4. Allocate a linked list; randomize next-pointer order.
-Step 5. Kernel body: block 0, thread 0 walks list for N hops.
-          uint64_t s = clock64(); walk(N); uint64_t e = clock64(); out[0] = e - s;
-Step 6. nvcc -arch=sm_90a -O3 -std=c++17 -lineinfo -o probe probe.cu
-Step 7. Run 4096 trials → median / p10 / p90 of cycles-per-hop.
-Step 8. Write the probe record to
-          sources/experience/hw-probes/<level-slug>/<YYYY-MM-DD>-<task-slug>.md
-        and link it from the target skill.md's ## Measured Characteristics
-        section. **Not in skill verified.md** (dropped in MVP).
-```
-
-## Protocol — Feature sweep (deferred execution)
-
-See booklet 07 §R.4.5.3 for the full six-step workflow. MVP only scaffolds this path; actual execution waits for:
-
-- F0 source corpus formalization (so the whitepaper location is canonical), and
-- 40-hardware-feature layer (so the sweep results have a facts-layer home).
-
-When R11/R12 become available, this file will be extended with the whitepaper → ledger → grid probe workflow. Until then, if a task requires DSMEM / TMA / wgmma / setmaxnreg microbench, stop and record `status: blocked`.
-
-## Agent decision: which protocol to use
-
-| Task asks for... | Use... |
-| --- | --- |
-| Semantics of a single API (does `__shfl_xor_sync` support lane masking on Hopper?) | `api-probing.md` |
-| Cycle-level cost of an instruction (how fast is `fma.rn.f32`?) | This file — compute latency protocol |
-| Memory-level latency curve (SMEM vs L1 vs L2 vs HBM) | This file — pointer-chasing protocol |
-| Bandwidth or latency of a feature the whitepaper announces (TMA, DSMEM cluster, wgmma) | Record `status: blocked` with reference to `reasoning/hardware-microbench.md` §deferred — MVP does not execute feature sweeps |
-
-## Out of scope (MVP)
-
-- DSMEM cluster-size sweeps (tensor-core / Hopper territory).
-- TMA bandwidth characterization (tensor-core territory).
-- wgmma throughput per tile/dtype (tensor-core territory).
-- Whitepaper-driven feature-sweep execution end-to-end.
-- NVML-based clock_policy verification (until M5).

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/reasoning/optimization-reasoning/cross-warp-thinking.md

@@ -1,75 +0,0 @@
-# Reasoning Pattern: Cross-Warp Thinking
-
-## Core Question
-When optimizing at the single-block level, ask yourself: "Am I missing opportunities by not thinking about cooperation across blocks or across the cluster?"
-
-## Thinking Framework
-
-### Step 1: Identify what each block does independently
-- What data does each block load from global memory?
-- Is there overlap between the data loaded by neighboring blocks?
-- Are blocks producing partial results that need to be combined?
-
-### Step 2: Check for cross-block cooperation opportunities
-- **Shared data**: Can multiple blocks share the same loaded data via multicasting or caching?
-- **Shared computation**: Can blocks cooperate on a larger computation unit (e.g., 2-CTA MMA)?
-- **Communication**: Can blocks exchange intermediate results via distributed shared memory (DSMEM)?
-- **Scheduling**: Can blocks coordinate to improve cache behavior or load balancing?
-
-### Step 3: Evaluate the cooperation mechanism
-- Thread block clusters: guarantee co-scheduling on same GPC, enable DSMEM
-- TMA multicast: load data once, deliver to multiple CTAs in cluster
-- Distributed shared memory: CTAs in cluster can read/write each other's SMEM
-- Cluster-level barriers: synchronize across CTAs in a cluster
-- Trade: cluster cooperation adds synchronization overhead; only beneficial when data sharing is significant
-
-## Examples from Literature
-
-### Example 1: TMA Multicast -- Don't Load the Same Tile Twice
-**From:** CUTLASS GEMM with Thread Block Clusters on Blackwell (Colfax)
-
-**Single-block view:** Each CTA in a GEMM grid loads its own bMxbK tile of A and bNxbK tile of B from global memory. CTAs in the same column of the output grid load the same A tile; CTAs in the same row load the same B tile.
-
-**Cross-block insight:** With a 2x2 cluster, 4 CTAs share 2 A tiles and 2 B tiles. Without multicasting, each CTA loads 2 tiles = 8 total loads. With TMA multicast, each tile is loaded once and delivered to all CTAs that need it = 4 total loads. This halves global memory traffic.
-
-**Implementation:** Each CTA constructs a bitmask indicating which cluster members share its operand tile. For operand A, the mask includes all CTAs in the same row of the cluster. For B, all CTAs in the same column. The TMA instruction uses this `ctaMask` to multicast.
-
-**Example for 4x4 cluster, CTA 0:**
-- `tma_bitmask_a = 0x1111` (CTAs 0, 4, 8, 12 -- same row)
-- `tma_bitmask_b = 0x000f` (CTAs 0, 1, 2, 3 -- same column)
-- Each CTA loads only its 1/4 slice of the tile; multicast delivers it to all participants
-
-### Example 2: 2-CTA MMA -- Two Blocks as One Compute Unit
-**From:** CUTLASS GEMM with Thread Block Clusters, FlashAttention-4 (Colfax)
-
-**Single-block view:** Each CTA computes a bMxbN output tile using its own tensor core resources. The MMA atom size is limited by single-SM resources.
-
-**Cross-block insight:** Blackwell's 2-CTA MMA (`tcgen05.mma` with cta_group::2) allows a pair of CTAs to cooperate on a single MMA spanning both SMs' TMEM and tensor cores. The effective atom size doubles to 256x256x16 (from 128x256x16). This reduces per-CTA shared memory traffic because operand B is shared across the pair.
-
-**Benefit in attention backward:** SMEM bandwidth is the bottleneck. 2-CTA MMA roughly halves the per-CTA operand B traffic. Additionally, the dQ reduction that would require atomics across CTAs now happens within the CTA pair via DSMEM exchange.
-
-### Example 3: DSMEM Exchange for Cross-CTA Data Sharing
-**From:** FlashAttention-4 backward pass (Colfax)
-
-**Single-block view:** In attention backward, each CTA computes dS (gradient of attention scores). For the dQ GEMM, the reduction axis is split across the 2-CTA pair, meaning each CTA holds half the dS data.
-
-**Cross-block insight:** Instead of writing partial dS to global memory and re-reading it, the two CTAs exchange their halves of dS via distributed shared memory (DSMEM). Each CTA writes its half to SMEM, and the partner CTA reads it via `ld.shared::cluster`. This repacks dS so each CTA has the full reduction data for its output rows, enabling the dQ MMA without global memory round-trip.
-
-**Key design decision:** The pipeline is reordered to overlap DSMEM exchange latency with other computation. Compute dP for the current tile while exchanging dS and computing dQ for the previous tile.
-
-### Example 4: Cluster-Level Synchronization -- Not Just cluster_sync
-**From:** CUTLASS Blackwell examples (Colfax)
-
-**Naive approach:** Use `cute::cluster_sync()` after every pipeline stage to ensure all CTAs are done before any issues new TMA loads.
-
-**Cross-block insight:** `cluster_sync()` is overkill because not all CTAs share all data. CTA 0 only needs to wait for CTAs that share its A tile (same row) and its B tile (same column), not ALL CTAs in the cluster.
-
-**Solution:** Use targeted mbarrier synchronization. The post-MMA barrier's bitmask is the bitwise OR of the A and B multicast bitmasks. For CTA 0 in a 4x4 cluster: `mma_bitmask = 0x1111 | 0x000f = 0x111f`. This allows CTAs that don't share data to run ahead independently, reducing synchronization overhead.
-
-## When This Pattern Applies
-- Multiple blocks load the same data (e.g., shared A/B tiles in GEMM, shared KV in attention)
-- The per-block problem is small relative to the hardware (under-utilizing SMs)
-- Inter-block reduction is needed (e.g., Split-K, dQ accumulation)
-- SMEM or register pressure per block is the bottleneck (spreading across blocks helps)
-- Architecture supports clusters (Hopper+) with DSMEM and TMA multicast
-- Moving from Hopper to Blackwell: 2-CTA MMA is a new cross-block cooperation mode

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/reasoning/optimization-reasoning/idle-resource-detection.md

@@ -1,67 +0,0 @@
-# Reasoning Pattern: Idle Resource Detection
-
-## Core Question
-When a hardware unit or a group of threads is idle during some phase, ask yourself: "What useful work could this idle resource be doing instead?"
-
-## Thinking Framework
-
-### Step 1: Identify what is idle and when
-- Are some warps waiting at a barrier while others compute?
-- Is the memory subsystem idle while compute units are busy (or vice versa)?
-- Are specific hardware units (SFU, tensor cores, load/store units) underutilized?
-- Is there dead time between kernel launches or between pipeline stages?
-
-### Step 2: Match idle resources to available work
-- If threads are idle: can they prefetch data, compute statistics, or handle bookkeeping?
-- If memory units are idle: can they start loading data for future iterations?
-- If compute units are idle: can they process non-critical-path work (softmax, normalization)?
-- If tensor cores are idle: can they do a preparatory MMA for the next tile?
-
-### Step 3: Design the overlap
-- Use warp specialization to assign different work to different thread groups
-- Use async operations (TMA, WGMMA) to decouple issuance from completion
-- Use producer-consumer patterns with barriers to synchronize access
-- Account for resource constraints: shared memory, registers, barrier objects
-
-## Examples from Literature
-
-### Example 1: Warp Specialization -- Producer Warps Are Idle After TMA Issue
-**From:** CUTLASS Pipelining Tutorial, Developing CUDA Kernels for GEMM on Hopper (Colfax)
-
-**Idle resource identified:** In a GEMM mainloop, TMA load is issued by a single thread. After issuing the TMA instruction, the entire producer warpgroup has nothing to do until the next pipeline stage needs to be loaded. On Hopper, TMA is so lightweight that the producer warp spends most of its time idle.
-
-**Solution:** Warp specialization formalizes this: dedicate one warpgroup to TMA (producer) and give the remaining warpgroups to WGMMA (consumers). Since the producer is idle most of the time, it needs very few registers. Use `setmaxnreg` to deallocate the producer's excess registers (down to 24-40 per thread) and reallocate them to consumers (up to 240-256 per thread). This converts idle thread registers into active compute resources.
-
-**Key insight:** The producer warpgroup is "paying" 128 threads worth of occupancy for minimal work. The optimization is not about making the producer faster -- it's about reclaiming the resources those idle threads hold.
-
-### Example 2: FlashAttention-3 Pingpong -- One Warpgroup Idle During Other's GEMM
-**From:** FlashAttention-3 (Colfax)
-
-**Idle resource identified:** With 2 consumer warpgroups doing attention, when warpgroup 1 is executing WGMMA (which occupies the tensor cores), warpgroup 2's threads are idle. The CUDA cores and SFU units are not being used during the WGMMA execution.
-
-**Solution:** Schedule warpgroup 2 to do softmax (which uses CUDA cores for FMA and SFU for exp) while warpgroup 1 does GEMM (which uses tensor cores). Then swap. This "pingpong" schedule overlaps tensor core work with CUDA core + SFU work.
-
-**Result:** 570 -> 620 TFLOPS improvement on H100 for FP16 attention forward pass. The idle CUDA cores/SFU during WGMMA are now doing softmax.
-
-### Example 3: Intra-Warpgroup Overlap -- Threads Idle Between WGMMA Issue and Completion
-**From:** FlashAttention-3, CUTLASS Pipelining Tutorial (Colfax)
-
-**Idle resource identified:** WGMMA is asynchronous: after `warpgroup_commit_batch()`, the 128 threads in the warpgroup are free to do other work until `warpgroup_wait<0>()`. During this window, the threads' integer/FP ALUs are idle.
-
-**Solution:** Insert non-MMA work (softmax partial computation, index calculation, pipeline state management) between commit and wait. This uses the threads' ALUs while the tensor cores execute WGMMA independently.
-
-**Result:** Additional ~20-40 TFLOPS improvement in FlashAttention-3 (620 -> 660 TFLOPS). Higher register pressure is the cost.
-
-### Example 4: Blackwell UMMA -- Single-Thread Launch Frees 127 Threads
-**From:** FlashAttention-4, CUTLASS Blackwell Tutorials (Colfax)
-
-**Idle resource identified:** On Blackwell, `tcgen05.mma` is launched by a single thread. The other 127 threads in the warpgroup are completely idle during the MMA launch sequence.
-
-**Solution:** Those idle threads can handle softmax computation, data staging in TMEM, synchronization bookkeeping, and DSMEM exchanges for 2-CTA mode. The single-thread MMA launch makes warp specialization even more natural: one thread issues MMA, the rest do everything else.
-
-## When This Pattern Applies
-- Profiler shows low utilization of specific hardware units (tensor cores, SFU, LSU)
-- Warp stall analysis shows significant "barrier wait" or "not selected" stalls
-- Pipeline visualization shows gaps between stages
-- One warpgroup consistently finishes before another in a multi-warpgroup design
-- Async operations (TMA, WGMMA, tcgen05.mma) create natural idle windows

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/reasoning/optimization-reasoning/resource-freed-then-what.md

@@ -1,67 +0,0 @@
-# Reasoning Pattern: Resource Freed Then What
-
-## Core Question
-When an optimization eliminates a bottleneck or frees a resource, ask yourself: "Now that this resource is freed, what new opportunity does that create?"
-
-## Thinking Framework
-
-### Step 1: Identify what was freed or reduced
-- A memory access was eliminated (e.g., no longer need to write intermediate to HBM)
-- A compute unit was freed (e.g., producer warps are idle after issuing TMA)
-- Register pressure was reduced (e.g., TMA handles index computation, freeing registers)
-- SMEM capacity was freed (e.g., eliminated a buffer that's no longer needed)
-- A latency was hidden (e.g., pipelining hides copy latency)
-
-### Step 2: Check cascading opportunities
-- Can we use the freed resource to increase the problem size we handle?
-  - Larger tiles, deeper pipelines, more accumulators in flight
-- Can we use the freed resource to do additional work?
-  - Fuse another operation, overlap a different computation
-- Can we trade the freed resource for a different kind of improvement?
-  - Convert freed SMEM into more pipeline stages
-  - Convert freed registers into larger tile sizes
-  - Convert hidden latency into higher throughput
-
-### Step 3: Evaluate the second-order effects
-- Does the new opportunity shift the bottleneck somewhere else?
-- Are there constraints that prevent exploiting the freed resource?
-- What is the marginal value of this resource given the current bottleneck?
-
-## Examples from Literature
-
-### Example 1: FlashAttention -- Eliminating HBM Access Enables Larger Tiles
-**From:** FlashAttention (Dao et al.) / FlashAttention-2 Hopper case study (Colfax)
-
-**What was freed:** By computing attention tile-by-tile with online softmax, the full N x N attention matrix never needs to be materialized in HBM. This eliminates O(N^2) memory traffic.
-
-**Cascading opportunity:** Since HBM bandwidth is no longer the bottleneck, the kernel can now use larger tile sizes (Br, Bc) to increase arithmetic intensity. The freed memory bandwidth budget means we can invest it in loading larger Q, K, V tiles per iteration. Larger tiles also mean fewer iterations of the outer loop, reducing per-iteration overhead (synchronization, softmax statistics updates).
-
-**Second-order effect:** With larger tiles, register pressure increases (need to hold larger accumulators). This shifts the bottleneck to registers, which is then addressed by warp specialization with setmaxnreg.
-
-### Example 2: TMA Frees Registers -- Enables Deeper Pipelines
-**From:** CUTLASS Pipelining Tutorial (Colfax)
-
-**What was freed:** On Hopper, TMA handles all address calculation and boundary predication in hardware. This frees the registers that previously held loop indices, predicate masks, and address calculations (significant on Ampere where cp.async still needs register-held addresses).
-
-**Cascading opportunity:** The freed registers can be re-invested in:
-- More pipeline stages (each stage needs register state for pipeline tracking)
-- Larger tile sizes (larger WGMMA atoms, wider N dimension)
-- Holding multiple accumulators simultaneously (critical for fused kernels like FlashAttention)
-
-**Second-order effect:** With more pipeline stages and larger tiles, SMEM consumption increases. The optimization chain is: TMA frees registers -> larger tiles/more stages -> more SMEM needed -> must balance against SMEM capacity limit.
-
-### Example 3: FlashAttention-4 -- Software Exp Frees SFU Bottleneck
-**From:** FlashAttention-4 (Colfax)
-
-**What was freed:** On Blackwell, the SFU (special function unit) for exponential is a bottleneck: tensor cores are 512x faster than SFU. FlashAttention-4 offloads part of the exp computation to FMA units via polynomial approximation, effectively doubling exp throughput.
-
-**Cascading opportunity:** With the SFU bottleneck partially relieved, the kernel can now better overlap softmax with MMA. The pingpong schedule between warpgroups becomes more effective because the softmax phase completes faster, keeping tensor cores busy for a larger fraction of time.
-
-**Second-order effect:** Using FMA for software exp means those FMA units are unavailable for other elementwise work. But since FMA units are abundant and tensor cores handle the heavy computation, this trade is favorable.
-
-## When This Pattern Applies
-- After successfully eliminating a memory bottleneck (coalescing, caching, tiling)
-- After reducing register pressure (TMA, setmaxnreg, moving data to TMEM)
-- After hiding a latency (pipelining, async operations)
-- After fusing operations (fewer kernel launches = freed launch overhead budget)
-- Whenever a profiling run shows that the "old" bottleneck is no longer the top issue

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/reasoning/task-packet.md

@@ -1,122 +0,0 @@
-# Task Packet Contract (N3)
-
-The KB-gen agent takes exactly one input: a YAML file under `tasks/`. This file is the **task packet**. If any required field is missing or malformed, the agent refuses to start.
-
-## Required fields
-
-```yaml
-task_id: 2026-04-15-warp-primitives         # unique, date-prefixed, kebab-case
-task_type: build-skill                      # see enum below
-target_path: wiki/nvidia/foundations/compute/warp-primitives/   # relative to , ends in / for dir or .md for file
-hardware:
-  device: H200
-  sm: "9.0a"
-  cuda_runtime: "12.4"
-upstream_scope:                              # absolute paths OR -relative paths under corpus/nvidia/; agent forbidden to grep outside
-  - corpus/nvidia/cuda-official/cuda-toolkit-documentation-13.2/   # -relative entry under 05-source-corpus is allowed
-  - {{CCCL_REPO_REF}}/cub/                        # absolute path is also allowed
-references:                                  # meta-skills the agent must read first
-  - reasoning/api-probing.md
-  - reasoning/hardware-microbench.md
-  - reasoning/benchmark-protocol.md
-  - reasoning/bottleneck-triage.md
-success_criteria:                            # self-checked before done-report (MVP rules)
-  - file_exists: skill.md                    # required
-  - file_exists: pitfalls.md                 # required
-  - lint_clean: true
-  - at_least_one_hw_probe_linked: true       # skill.md's ## Measured Characteristics must link ≥1 record under sources/experience/hw-probes/
-  # apis.md is OPTIONAL — only required when the skill touches named APIs.
-  #   If this task expects apis.md, add an explicit line:
-  #     - file_exists: apis.md
-  # verified.md is DROPPED in MVP — do not include it.
-```
-
-## `task_type` enum
-
-| Value | Meaning | Typical output |
-| --- | --- | --- |
-| `build-skill` | Produce a skill four-pack under `wiki/nvidia/foundations/<family>/<skill>/` | `skill.md` (REQUIRED) + `pitfalls.md` (REQUIRED) + `apis.md` (OPTIONAL — when the skill touches named APIs). `verified.md` is dropped in MVP; do not create it. |
-| `probe-api` | Run an F10 probe on one API and back-fill `wiki/nvidia/api-definitions/` | `sources/experience/api-probes/...` + updated `wiki/nvidia/api-definitions/...` |
-| `build-pattern` | Produce a pattern four-pack under `wiki/nvidia/operator-routing/cuda-core/<op>/` | `INDEX.md` + `ROUTING.md` + `library-fallback.md` + `TASK-PACKET.md` |
-| `introspect-hardware` | Run `kp_introspect` and populate `00-foundation/hardware-spec/` | updated `h200-specs.md` + `runtime-introspection/bundle-*.json` |
-| `build-hardware-feature` | Produce a hardware-feature four-pack under `wiki/nvidia/hardware/<feature>/` (TMA, wgmma, DSMEM, cluster-launch-control, …). `target_path` is the feature directory; companion outputs (code skeleton, hw-probe record) live outside that directory and MUST be listed under `also_writes:`. | `skill.md` + `pitfalls.md` (under `target_path`); `*.cu` + `build.sh` under `wiki/nvidia/code-walkthroughs/<source-repo>/<feature>/`; `<YYYY-MM-DD>-<slug>.md` under `sources/experience/hw-probes/<feature>/` |
-| `extend-hardware-feature` | Append measured material to an existing `wiki/nvidia/hardware/<feature>/skill.md` (typically a shape sweep or follow-up probe) without changing the skill's identity. `target_path` MUST be the existing feature directory; new probe records under `sources/experience/hw-probes/<feature>/` are listed in `also_writes:`. | Append `## Shape-selection guide` (or analogous section) to the existing `skill.md`; new `<YYYY-MM-DD>-<slug>.md` under `sources/experience/hw-probes/<feature>/` |
-| `build-classical-algo` | Produce a classical-algorithm four-pack under `wiki/nvidia/techniques/<algo>/` (warp-specialization, persistent-kernel, online-softmax, split-k, …). The algorithm code skeleton lives separately under `wiki/nvidia/code-walkthroughs/<source-repo>/<algo>/`; the A/B ablation record lives under `sources/experience/api-probes/<op>/`. | `skill.md` + `pitfalls.md` (under `target_path`); `*.cu` + `build.sh` under `wiki/nvidia/code-walkthroughs/<source-repo>/<algo>/`; `<YYYY-MM-DD>-<slug>-ablation.md` under `sources/experience/api-probes/<op>/` |
-
-### Rules for the cutlass-extraction task kinds (`build-hardware-feature`, `extend-hardware-feature`, `build-classical-algo`)
-
-These three kinds were added on 2026-04-28 to support `docs/15-代码仓库抽取知识流程_update_en.md`. All three obey the same guard rails:
-
-1. **`target_path` is deterministic** — exactly one directory, no `<slug>` placeholders, no `OR` alternatives. Resolve any landing-path choice to one path *in the task packet*, not at execution time.
-2. **All non-`target_path` outputs are listed under `also_writes:`**. The packet enumerates the exact directories the agent is allowed to touch (e.g. `wiki/nvidia/code-walkthroughs/<source-repo>/<topic>/`, `sources/experience/hw-probes/<feature>/`, `sources/experience/api-probes/<op>/`).
-3. **`upstream_repo_pin:` is required** — pin the source-repo commit (e.g. `cutlass@f74fea9c`) so the extracted skeleton is reproducible.
-4. **`source_anchors:` is required** — enumerate concrete files in the source repo (e.g. `examples/48_hopper_warp_specialized_gemm/48_hopper_warp_specialized_gemm.cu`, `include/cute/atom/copy_traits_sm90_tma.hpp`) so the agent does not browse blindly.
-5. **`success_criteria:` paths are concrete** — every `file_exists:` entry resolves to a literal path (no `<slug>`, `<YYYY-MM-DD>`, or `*`). Date and slug placeholders are forbidden because they prevent programmatic checking.
-6. **Stage 3.5 (AC-V) verdict is mandatory** before the task is considered complete; the packet's success-criteria block records the metrics that the experiment record must contain.
-
-If a task needs to land in one of two possible directories (e.g. AC-7 of the cutlass plan: `wiki/nvidia/foundations/compute/gemm-fused/` vs. `wiki/nvidia/operator-routing/fused-cuda-tensor-core/`), the task packet must commit to one before execution; the rationale goes in the per-task report.
-
-## Optional fields
-
-```yaml
-related_skills: [coalescing, vectorized-access]     # cross-reference hints for ROUTING.md
-prior_art:                                           # existing entries to extend or supersede
-  - path: wiki/nvidia/foundations/compute/warp-primitives/skill.md
-    relation: supersedes | extends | references
-deadline: 2026-04-20                                 # informational, soft
-notes: |                                             # free-form guidance from the human issuing the task
-  Focus on warp shuffle + vote families. Skip match.* for now — MVP out of scope.
-```
-
-## Field semantics
-
-- **`target_path`** — directory (trailing `/`) or file (ending `.md`). Agent refuses to write outside this path unless `also_writes:` is explicitly set.
-- **`upstream_scope`** — list of absolute paths or ``-relative paths under `corpus/nvidia/`. Agent uses these for `grep_source` / `read_file` on upstream material. Grepping outside this list is forbidden; reading `` and `tools/` is always allowed (for reading meta-skills and invoking the CLI tools).
-- **`references`** — meta-skill files the agent must read *before* generating any output. Agent confirms it has read them by listing their paths in the done-report.
-- **`success_criteria`** — checked programmatically by `lint_knowledge.py` + a self-review pass. Any failure → the agent reports what is missing and stops (no partial merge).
-
-## Example — `tasks/build-warp-primitives.yaml`
-
-```yaml
-task_id: 2026-04-15-warp-primitives
-task_type: build-skill
-target_path: wiki/nvidia/foundations/compute/warp-primitives/
-hardware:
-  device: H200
-  sm: "9.0a"
-  cuda_runtime: "12.4"
-upstream_scope:
-  - corpus/nvidia/cuda-official/cuda-toolkit-documentation-13.2/programming-guide/
-  - corpus/nvidia/cuda-official/cuda-toolkit-documentation-13.2/ptx-isa/
-  - {{CCCL_REPO_REF}}/cub/
-  - {{CUDA_SAMPLES_REPO_REF}}/
-references:
-  - reasoning/api-probing.md
-  - reasoning/hardware-microbench.md
-  - reasoning/benchmark-protocol.md
-  - reasoning/bottleneck-triage.md
-related_skills: [coalescing, vectorized-access]
-success_criteria:
-  - file_exists: skill.md
-  - file_exists: pitfalls.md
-  - file_exists: apis.md               # REQUIRED here because warp-primitives touches __shfl_sync / __ballot_sync etc.
-  - lint_clean: true
-  - at_least_one_hw_probe_linked: true # skill.md ## Measured Characteristics links ≥1 hw-probe
-notes: |
-  Cover shfl.sync (idx/up/down/bfly), vote.sync (ballot/all/any),
-  and one classical warp-reduce example (block-level sum of 1024 floats).
-  Skip match.sync and reduce.sync — deferred.
-  Agent writes its own compute-latency probe per hardware-microbench.md
-  §Compute latency protocol; canonical baseline from `kp_introspect microbench
-  compute-latency` may be cross-referenced but the per-skill probe is the
-  authoritative record for the skill-specific pattern.
-```
-
-## What happens on agent start
-
-1. Load `tasks/<task_id>.yaml`, validate against this schema. Refuse on error.
-2. Resolve `target_path` → absolute path under ``. Refuse if the path escapes ``.
-3. Read every file in `references:` sequentially. These become the agent's operational rules.
-4. Begin the build according to `task_type`.
-5. On finish, run `tools/lint_knowledge.py` over all written files. Fix any errors.
-6. Emit a done-report: touched files, measured results, unresolved gaps.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/references/examples.md

@@ -1,190 +0,0 @@
----
-version_sensitive:
-  id: vs-triton-3.6-blackwell-tcgen05
----
-
-# Worked Query Examples
-
-Concrete patterns showing how to translate a user question into a navigation path and synthesize an answer.
-
----
-
-## Example 1: "How do I write a fast GEMM kernel on B200?"
-
-**Navigation path**:
-1. `queries/by-kernel-type.md` → find `gemm` row → lists kernel pages
-2. Read `wiki/nvidia/kernels/fp8-block-scale-gemm.md` and `wiki/nvidia/kernels/nvfp4-gemm.md`
-3. Follow `sources:` to concrete PRs: `pr-cutlass-2139` (blockwise+groupwise GEMM), `pr-vllm-13798` (FP8 GEMM)
-4. For optimization path, read `wiki/nvidia/techniques/warp-specialization.md`, `wiki/nvidia/techniques/persistent-kernels.md`
-5. For progression, cite the tcgen05 tutorial (`sources/blogs/tcgen05-tutorial.md`): Naive 17% → Swizzling 46% → Pipelining 62% → Warp Spec 80% → 2-SM 86% → CLC 98%
-
-**Command**:
-```bash
-python3 scripts/query.py --type kernel --tag gemm --architecture sm100
-```
-
----
-
-## Example 2: "My kernel has low SM utilization on B200"
-
-**Navigation path**:
-1. `queries/by-problem.md` → find "low-sm-utilization" row
-2. Pattern page: `wiki/nvidia/patterns/low-sm-utilization.md`
-3. Candidate techniques: `technique-persistent-kernels`, `technique-tile-scheduling`, `hw-clc`
-4. Read the CLC page: `wiki/nvidia/hardware/clc.md` for code example
-5. Cite: tcgen05 tutorial showed 86% → 98% with persistent + CLC
-
-**Command**:
-```bash
-python3 scripts/query.py --symptom low-sm-utilization
-python3 scripts/get_page.py" pattern-low-sm-utilization
-```
-
----
-
-## Example 3: "Where is tcgen05.mma used in CUTLASS?"
-
-**Navigation path**:
-1. `queries/by-hardware-feature.md` → find `tcgen05` row → lists all relevant pages
-2. `queries/by-repo.md` → NVIDIA/cutlass section → 32 PRs
-3. Cross-reference via tag filter
-
-**Command**:
-```bash
-python3 scripts/query.py --tag tcgen05 --repo cutlass --limit 30
-python3 scripts/grep_wiki.py" "tcgen05\\.mma" --only sources
-```
-
-Tip: the `--tag` filter also accepts aliases, so `--tag UMMA` resolves to `tcgen05`.
-
----
-
-## Example 4: "Show me the FlashAttention-4 implementation details"
-
-**Navigation path**:
-1. Direct: `wiki/nvidia/kernels/flash-attention-4.md`
-2. Performance: 1605 TFLOPS on B200 BF16 (71% utilization)
-3. Techniques used: ping-pong scheduling, software exp, 2-CTA backward
-4. Follow sources → `sources/docs/flash-attention-4.md` (paper), `sources/blogs/flash-attention-4.md` (Tri Dao blog)
-
-**Command**:
-```bash
-python3 scripts/get_page.py" kernel-flash-attention-4 --follow-sources
-```
-
----
-
-## Example 5: "What's the difference between Hopper wgmma and Blackwell tcgen05?"
-
-**Navigation path**:
-1. `wiki/nvidia/migration/wgmma-to-tcgen05.md` — dedicated migration guide with explicit `architectures` metadata
-2. `wiki/nvidia/hardware/tcgen05-mma.md` — canonical reference for the new instruction
-3. Contrast with Hopper behavior implicit in the migration page
-
-**Command**:
-```bash
-python3 scripts/get_page.py" migration-wgmma-to-tcgen05
-python3 scripts/get_page.py" hw-tcgen05-mma
-```
-
----
-
-## Example 6: "How did teams in the GPU Mode NVFP4 Hackathon win?"
-
-**Navigation path**:
-1. `sources/contests/gpu-mode-nvfp4/` (4 problems)
-2. Each problem page has `submissions:` with rank 1/2/3 techniques
-3. Read participant blogs: `sources/blogs/yue-nvfp4-hackathon.md`, `sources/blogs/amandeep-nvfp4-attempts.md`, `sources/blogs/simon-nvfp4-gemv.md`
-4. Techniques: PTX-level control, cache policy differentiation, register budgeting
-
-**Command**:
-```bash
-python3 scripts/query.py --type contest --tag nvfp4
-python3 scripts/get_page.py" contest-gpumode-p1
-```
-
----
-
-## Example 7: "Write a Triton kernel for GatedDeltaNet decode on Blackwell"
-
-**Navigation path**:
-1. `wiki/nvidia/kernels/gated-delta-net.md` — conceptual + code
-2. `wiki/nvidia/languages/triton-blackwell.md` — current Triton 3.6+ Blackwell lowering surfaces (tcgen05 + TMEM via descriptor/TMA + warp_specialize, `tl.dot_scaled`, Gluon multi-CTA); pre-3.6 historical context preserved in a clearly-marked subsection
-3. Source PRs: `pr-vllm-*` for gated_delta, FlashInfer GDN kernels
-
-**Command**:
-```bash
-python3 scripts/query.py "gated delta net decode" --language triton
-```
-
----
-
-## Example 8: "What are the memory-bound kernel optimization tricks on B200?"
-
-**Navigation path**:
-1. `wiki/nvidia/patterns/memory-bound.md` — candidate techniques list
-2. `wiki/nvidia/techniques/vectorized-loads.md` — wide loads + cache policies (covers `evict_first` / `no_allocate`)
-3. Best case study: `wiki/nvidia/kernels/nvfp4-gemv.md` (2000μs → 22.4μs progression)
-
-**Command**:
-```bash
-python3 scripts/query.py --symptom memory-bound
-```
-
----
-
-## Example 9: "Find all FlashInfer PRs for FP8 MoE"
-
-**Command**:
-```bash
-python3 scripts/query.py --repo flashinfer --tag moe --limit 30
-python3 scripts/query.py --repo flashinfer --tag fp8 --limit 30
-python3 scripts/grep_wiki.py" "fp8" "moe" --only sources --files-only
-```
-
----
-
-## Example 10: "What PTX instructions are unique to SM100?"
-
-**Navigation path**:
-1. `wiki/nvidia/languages/ptx-sm100.md` — direct reference
-2. Cross-reference: tcgen05.alloc/mma/ld/st/dealloc/fence, clusterlaunchcontrol.try_cancel, cp.async.bulk.tensor multicast
-
-**Command**:
-```bash
-python3 scripts/get_page.py" lang-ptx --body-only
-python3 scripts/grep_wiki.py" "tcgen05" --only wiki --context 0
-```
-
----
-
-## Synthesis Pattern
-
-For most questions, a high-quality answer follows this shape:
-
-```
-1. Topic framing (1-2 sentences, cite wiki page)
-   → Pull from wiki/<section>/<topic>.md ## Overview
-
-2. Technical mechanism (cite hardware + technique pages)
-   → wiki/nvidia/hardware/*.md for hw details
-   → wiki/nvidia/techniques/*.md for optimization patterns
-
-3. Concrete code snippet (copy from wiki page, already validated)
-   → Every technique/kernel/language page has a compilable snippet
-
-4. Performance evidence (cite performance_claims)
-   → Always report gpu, dtype, shape, metric, value, source_id
-
-5. References (cite source IDs)
-   → PR: pr-cutlass-2139 → sources/prs/cutlass/PR-2139.md
-   → Blog/doc: blog-* / doc-*
-```
-
-## Anti-Patterns (Don't Do These)
-
-- Don't recommend techniques without citing `sources:` — the wiki exists precisely for this.
-- Don't quote performance without the full 6-field `performance_claims` record.
-- Don't conflate `sm90` and `sm100` patterns — always check the `architectures:` field.
-- For synthesis pages, do not cite `verified` claims without checking official-doc and upstream-code evidence. For experience pages, check that the stated scope matches the independently reproduced conditions.
-- Don't recommend DeepEP/DualPipe/EPLB — they're explicitly out of scope (kernel-only KB).