@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/provenance/releases/contract-atb/2026-10-10-validation.json

@@ -1,78 +0,0 @@
-{
-  "date": "2026-10-10",
-  "delivery": {
-    "tasks": 101,
-    "local_current_materializations": 101,
-    "mcp_bulk_preferred_kernel_returned": 101,
-    "support_records_hash_verified": 388,
-    "support_originals_checked": true,
-    "archive_runs": 573,
-    "archive_solution_versions_identity_verified": 2001,
-    "archive_contract_versions_hash_verified": 2160,
-    "implementation_evidence_tiers": {
-      "author-report-current-source": 19,
-      "historical-current-source-correctness": 55,
-      "source-only-direction": 27
-    },
-    "negative_controls_passed": true,
-    "model_or_device_execution": false,
-    "errors": []
-  },
-  "hot_evidence": {
-    "hot_files": 1880,
-    "hot_bytes": 25227094,
-    "catalog_sha256": "38bf5d7608cf92790a17bbe005829e3de88a69c9992a2b0d3bd5638b0000d920"
-  },
-  "archive": {
-    "release_url": "https://github.com/sii-ai-infra/KernelWiki-private/releases/tag/untagged-d851a54139cca15ca3b0",
-    "release_tag": "contract-atb-history-20261009",
-    "draft": true,
-    "asset_id": 626802225,
-    "downloaded_bytes": 55221272,
-    "download_sha256_matches": true
-  },
-  "historical_query_replay": {
-    "query_occurrences": 10431,
-    "tasks": 101,
-    "target_hits": {
-      "5": 1173,
-      "10": 1751,
-      "original": 1685,
-      "3": 813,
-      "1": 304,
-      "error:VENDOR_REQUIRED": 3
-    },
-    "task_coverage": {
-      "5": 95,
-      "10": 100,
-      "original": 99,
-      "3": 87,
-      "1": 63
-    },
-    "first_main_hits": {
-      "5": 42,
-      "10": 51,
-      "original": 50,
-      "1": 8,
-      "3": 32
-    },
-    "frozen_handler_equivalence_checks": 24,
-    "model_or_device_effect": false
-  },
-  "native_validator": {
-    "passed": true,
-    "summary": [
-      "Validated 4095 files (3480 source IDs collected)",
-      "Validated 1721 asset bundles (verbatim=1593, extracted=116, derived=12, orphan-source-files=0)",
-      "Validated 8 candidate ledgers"
-    ],
-    "warnings": 60
-  },
-  "limits": [
-    "No model or device execution.",
-    "Own-card findability is not judged relevance or optimization success.",
-    "Draft private data release must be published before reader archive rollout.",
-    "Existing repository-wide size gate fails on the base revision and remains unresolved; size budget was not relaxed.",
-    "Generic Codex skill validator rejects existing vendor/language/architecture/wiki_refs extensions; repository-specific strict validators pass."
-  ]
-}

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

@@ -1,151 +0,0 @@
-# KB-Gen Agent Contract
-
-> This directory is the **knowledge base being built**. Downstream
-> kernel-writing agents will later consume it. All content here is produced
-> by a **KB-generation agent** that obeys this file.
->
-> **Scope (updated 2026-04-28 by `docs/15-代码仓库抽取知识流程_update_en.md`)**:
-> CUDA-core single-kernel optimizations for H200 (sm_90a) **plus** tensor-core
-> primitives (TMA, wgmma) and fused cuda-core/tensor-core gemm flows extracted
-> from the cutlass repository. Multi-kernel system features remain layered
-> separately under `90-system-level/`. The previously deferred layers
-> `40-hardware-feature/`, `50-classical-algo/`, and `60-code/` (formerly
-> `60-cutlass-cute/`) are now in scope; `60-code/` uses a source-driven
-> second-level structure (`60-code/<source-repo>/`, e.g. `60-code/cutlass-cute/`).
-
----
-
-## Step 0 — Read these meta-skills before writing anything
-
-An agent starting any task under this directory MUST first read, in order:
-
-1. `reasoning/task-packet.md` — the input contract for a build task.
-2. `reasoning/api-probing.md` — the F10 protocol for probing an API you do not yet understand.
-3. `reasoning/hardware-microbench.md` — the protocol for **active microbenchmark probes** (compute-instruction latency, memory pointer chasing, whitepaper-driven feature sweeps). Use this whenever a task needs cycle-level or bandwidth facts that the passive introspection APIs cannot give.
-4. `reasoning/benchmark-protocol.md` — the N2 protocol for reproducible measurement.
-5. `reasoning/bottleneck-triage.md` — the decision tree for picking the next skill when a benchmark falls short.
-6. `templates/frontmatter/*.yaml` — required frontmatter schemas per layer.
-7. `corpus/nvidia/RETRIEVAL.md` — the retrieval contract for upstream materials.
-8. `corpus/GLOBAL_VARIABLES.md` — placeholder variables for local paths or hosted mirrors.
-
-If any of these files is missing, stop and report — do not improvise.
-
-**How to decide between `api-probing.md` and `hardware-microbench.md`**:
-- If the task asks *"what does this API do / how do I call it?"* → `api-probing.md`.
-- If the task asks *"how fast is this instruction / how many cycles does this memory level cost?"* → `hardware-microbench.md`.
-- If the task asks for a hardware-new-feature characterization driven by an architecture whitepaper (TMA, DSMEM cluster size sweep, wgmma throughput, setmaxnreg effect) → `hardware-microbench.md` §Feature sweep. **MVP status (updated 2026-04-28)**: active when the task is part of the cutlass-extraction roadmap (see `docs/15-代码仓库抽取知识流程_update_en.md`). Hardware-feature skills land under `40-hardware-feature/<feature>/`; their measurement records go to `80-experience/hw-probes/<feature>/`.
-
----
-
-## Layer responsibilities (MVP subset)
-
-| Layer | Purpose | Entry format | Who writes |
-| --- | --- | --- | --- |
-| `00-foundation/hardware-spec/` | H200 static spec + runtime introspection bundles | `.md` + `.json` | `tools/kp_introspect.py` (M2/M3) + agent to narrate |
-| `05-source-corpus/` | Manifest-backed source registry and retrieval contract for upstream docs / blogs / source repos | `MANIFEST.yaml` + `RETRIEVAL.md` + generated indexes | Humans + retrieval tools; **agent reads only** |
-| `10-api-raw/<ns>/<func>.md` | Authoritative signature + minimal usage per API | Strict schema: see `templates/frontmatter/api-raw.yaml` | Agent (during skill build or standalone API probe) |
-| `20-pattern/cuda-core/<op>/` | Operator-entry four-pack: `INDEX.md` / `ROUTING.md` / `library-fallback.md` / `TASK-PACKET.md` | One directory per operator | Agent (M6) |
-| `30-skill/<family>/<skill>/` | Single-kernel optimization technique. MVP: `skill.md` (required) + `pitfalls.md` (required) + `apis.md` (optional, when skill touches APIs). `verified.md` is dropped in MVP. | Schema: `templates/frontmatter/skill.yaml` | Agent (M4c, M5) |
-| `40-hardware-feature/<feature>/` | Hardware-new-feature characterization (TMA, wgmma, DSMEM, async-pipeline, setmaxnreg, …). Same four-file convention as `30-skill/`: `skill.md` (required) + `pitfalls.md` (required) + `apis.md` (optional). `evidence_level: measured` requires a `## Measured Characteristics` section pointing at `80-experience/hw-probes/<feature>/...`. | Schema: `templates/frontmatter/hardware-feature.yaml` (extends `skill.yaml` with `requires_sm` ≥ 9.0) | Agent (driven by `docs/15-代码仓库抽取知识流程_update_en.md`) |
-| `50-classical-algo/<algo>/` | End-to-end classical optimization algorithms extracted from upstream code (warp-specialization, persistent-kernel, online-softmax, split-k, …). Same four-file convention as `30-skill/`. Algorithm skeleton code lives separately under `60-code/<source-repo>/<algo>/`. | Schema: `templates/frontmatter/classical-algo.yaml` (extends `skill.yaml`) | Agent (driven by `docs/15-代码仓库抽取知识流程_update_en.md`) |
-| `60-code/<source-repo>/<topic>/` | Code-repository extraction layer: **library-usage knowledge** for upstream operator libraries (cutlass / cute on Hopper; vllm; …). Per-topic directories carry `README.md` (when-to-use + knob catalogue), `tuning.md` (template-parameter search log + configuration strategy), and optional `<feature>_skeleton.md` (line-numbered tour of the upstream code). Buildable `.cu` / `build.sh` files do **not** live here — the canonical reproducible binaries are under `80-experience/<api-probes|hw-probes>/<topic>/artifacts/`. Exception: `60-code/ptx-gemm/` keeps its `.cu` because the cutlass-free track has no upstream example to point at. Lint exempts the whole subtree from frontmatter requirements. | — | Agent (driven by `docs/15-代码仓库抽取知识流程_update_en.md`) |
-| `70-reasoning/` | Meta-skills (handwritten, frozen) | — | Humans only; **agent is forbidden to write here** |
-| `80-experience/api-probes/` | F10 API-semantics probe products | Schema: `templates/frontmatter/experience.yaml` | Agent (during API probe) |
-| `80-experience/hw-probes/` | Hardware microbench probe products (compute-latency / memory-latency); `skill.md` links here via `## Measured Characteristics` | Schema: `templates/frontmatter/experience.yaml` | Agent (during microbench, see `reasoning/hardware-microbench.md`) |
-| `90-system-level/<sub-area>/` | Kernel-boundary and multi-kernel concerns (launch overhead, CUDA graphs, stream concurrency, host-device transfer, …) — operator-invariant, not referenced from `20-pattern/` ROUTING. Loaded on demand from `reasoning/bottleneck-triage.md` when the symptom matches. See `90-system-level/reasoning/AGENTS.md` for the layer contract and roadmap. | `skill.md` + `apis.md` + `pitfalls.md` (same four-file convention as `30-skill/`) | Agent |
-| `templates/frontmatter/` | YAML schemas for every layer's frontmatter | — | Humans only |
-
-Layer `07-wiki/` remains **out of scope** in MVP; do not create it. `40-hardware-feature/`, `50-classical-algo/`, and `60-code/` were deferred post-MVP at first but became **active** on 2026-04-28 under the cutlass-extraction plan (`docs/15-代码仓库抽取知识流程_update_en.md`); content there must follow the same evidence/source/artifact rules as `30-skill/`. `90-system-level/` is built incrementally — only `launch-overhead/` exists today; other sub-areas stay pending until a task needs them.
-
----
-
-## Hard constraints (all enforced by `tools/lint_knowledge.py`)
-
-1. **No imagination**. Every factual claim in any generated `.md` must be grounded in one of:
-   - (a) a grepped upstream document or source code path (record in `source:`),
-   - (b) a runnable code artifact the agent itself built and ran (record in `artifacts.code`/`artifacts.build`),
-   - (c) a `kp_introspect` bundle (record in `artifacts.introspection`).
-
-   Any factual claim without grounding → either downgrade `evidence_level` to `inferred` or delete the claim.
-
-2. **Frontmatter is mandatory**. Every generated `.md` starts with a YAML block that satisfies the relevant template under `templates/frontmatter/`. The agent runs `lint_knowledge.py` against its own output before declaring the task done.
-
-3. **Language is English only**. Agent-facing consistency trumps translation comfort. File names, directory names, frontmatter field values, body prose, and code comments are all English. (User-facing READMEs in Chinese are fine — those live outside `knowledge/`.)
-
-4. **Measured means bound**. Any entry with `evidence_level: measured` MUST populate:
-   - `artifacts.code` — relative path to the probe or microbenchmark `.cu`
-   - `artifacts.build` — the exact `nvcc` command or a `build.sh` path
-   - `artifacts.introspection` — a `kp_introspect bundle --output <path>` json
-   - `measured_on` — device name + sm + cuda runtime + driver
-   Missing any of these → `lint_knowledge.py` rejects the file.
-
-5. **Source provenance**. `source:` lists at least one `{path, anchor}` entry. `path:` is absolute (for upstream `cuda_document/` / `cuda_repo/`) or repo-relative (for `knowledge/` internal links). `anchor:` is either a heading slug or a `Lxxx-Lyyy` line range. An optional `excerpt:` short quote is welcome. When referencing original upstream material, prefer `05-source-corpus/...` paths produced by the retrieval module instead of raw absolute paths.
-
-6. **Never touch `70-reasoning/`**. Meta-skills are frozen. If you find a gap, report it in the final done-report; do not rewrite them.
-
-7. **Target hardware is fixed**. MVP assumes H200 = sm_90a exclusively. Do not add multi-target variants or SM compatibility flags.
-
-8. **Skill contract** (MVP-simplified). When building `30-skill/<family>/<name>/`, the mandatory deliverables are:
-   - **`skill.md`** (REQUIRED) — narrative: what the technique is, why it helps, when to use it, when not to, plus a `## Measured Characteristics` section that links to the hw-probe records under `80-experience/hw-probes/<probe-slug>/...md` produced during this task.
-   - **`pitfalls.md`** (REQUIRED) — known failure modes and how to detect them.
-   - **`apis.md`** (OPTIONAL) — machine-readable list of APIs touched by this skill, each linked to `10-api-raw/`. **Only create this file when the skill actually touches named APIs**. Pure programming-pattern skills (e.g., loop unrolling, tiling) skip it.
-   - **`verified.md`** — **DROPPED in MVP**. Its post-MVP semantics ("marks whether this skill is used by a real kernel") are not needed yet; do not create this file.
-
-   **Where measured data lives** (MVP): microbench results from the agent's own probe runs go into `80-experience/hw-probes/<instruction-or-level-slug>/<YYYY-MM-DD>-<task-slug>.md` with the `experience.yaml` frontmatter. `skill.md` then points at those files via `## Measured Characteristics` bullets. **Do not embed a benchmark table inline in `skill.md`** — the probe record is the single source of truth.
-
-9. **Pattern four-pack contract**. When building `20-pattern/cuda-core/<op>/`, you produce exactly:
-   - `INDEX.md` — decision tree: library-first → custom.
-   - `ROUTING.md` — skill whitelist for this operator (only references skills already present under `30-skill/`).
-   - `library-fallback.md` — documented torch / cub / cuBLAS paths with shape ranges.
-   - `TASK-PACKET.md` — the operator-specific task packet (refines `reasoning/task-packet.md`).
-
----
-
-## Task lifecycle
-
-```
-tasks/<task_id>.yaml
-        │
-        ▼
-Agent loads task, reads 70-reasoning/* meta-skills
-        │
-        ▼
-Agent searches 05-source-corpus via `source_search` / `source_read` for relevant material
-        │
-        ▼
-(optional) Agent invokes kp_introspect for hardware facts
-        │
-        ▼
-(optional) Agent writes a minimal probe .cu, runs nvcc, measures latency per benchmark-protocol.md
-        │
-        ▼
-Agent writes output files under target_path
-        │
-        ▼
-Agent runs tools/lint_knowledge.py on output; fixes errors
-        │
-        ▼
-Agent emits a done-report:
-  - touched files
-  - measured results (if any)
-  - unresolved gaps (for human follow-up)
-```
-
----
-
-## Forbidden behaviors
-
-- Writing into `70-reasoning/`.
-- Writing files outside `target_path` (unless the task explicitly says `also_writes:`).
-- Reading files outside `upstream_scope` + `knowledge/` + `tools/`.
-- Grepping absolute upstream paths (`{{CUDA_REPO_ROOT}}`, repo-specific `*_REPO_REF`, or `{{CLAUDE_RESEARCH_REF}}`) directly. Use relative paths under `05-source-corpus/` via the retrieval module instead.
-- Using a baseline that is not recorded in `verified.md`.
-- Declaring `status: verified` without `evidence_level: measured` + full `artifacts` block.
-- Running `nvcc` with `-arch` other than `sm_90a` (MVP is H200-only).
-- Introducing any file outside English (see constraint 3).
-
----
-
-## When you are stuck
-
-If a task cannot converge (for example, an API under probe is undocumented everywhere in `upstream_scope`), the agent stops, writes a stub with `status: blocked` and a concrete question, and returns a done-report listing the blockers. **Do not guess.**

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

@@ -1,99 +0,0 @@
-# API Probing Protocol (F10, skeleton)
-
-> **Version**: MVP skeleton (~50 lines of executable rules). The full version
-> (discrepancy handling, multi-kernel probes, NVML clock verification, source
-> corpus formalization) is deferred until after MVP ships.
->
-> **Sibling protocol**: `hardware-microbench.md` covers **active** microbench
-> probes (cycle-level compute latency, pointer-chasing memory latency,
-> whitepaper-driven feature sweeps). **This file** covers **single-API
-> semantics** probes. They share benchmark-protocol.md, artifacts schema,
-> and frontmatter, but they answer different questions:
-> - `api-probing.md`: "what does this API do / how do I call it?"
-> - `hardware-microbench.md`: "how fast is this instruction / memory level?"
-
-The purpose of a probe is to turn an API that the knowledge base merely *lists* into an API that the knowledge base *demonstrates*. A probe is successful when, after it finishes, a downstream agent writing a kernel can copy-paste the probe record and get working, measured code.
-
-## When to probe
-
-Trigger a probe when any of these conditions is true:
-
-- A `wiki/nvidia/api-definitions/<ns>/<func>.md` exists but has no `## End-to-End Example` section.
-- A `wiki/nvidia/foundations/**/apis.md` lists an API that is absent from `wiki/nvidia/api-definitions/`.
-- The gap queue (`sources/experience/api-probes/_gap-queue.md`) has a pending entry pointing at this API.
-- A skill build task (M4c/M5) needs an API whose semantics you cannot fully justify from `upstream_scope` grep alone.
-
-## Protocol (6 steps, all mandatory)
-
-### Step 1 — Read upstream first
-
-Before writing any experimental code, query the source corpus:
-
-```bash
-python3 -m scripts.source_corpus.cli search '<api-symbol>' --scope cuda-official
-python3 -m scripts.source_corpus.cli search '<api-symbol>' --scope source-code/cuda-samples
-python3 -m scripts.source_corpus.cli read 'cuda-official/toolkit-docs-13.2/CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md' --anchor 'L120-L140'
-```
-
-Collect every hit as `{path, line_range}` and store it in the probe record's `source_refs:` field. If zero hits, mark the probe `kind: undocumented`, write the stub, and stop — ask a human to decide scope.
-
-### Step 2 — Write a minimal kernel
-
-Rules for the probe kernel:
-
-- One `.cu` file, ≤ 80 lines including host.
-- Uses only the API under probe plus trivial scaffolding (malloc / H2D / launch / D2H / free).
-- A fixed, documented launch config (grid + block + smem) — no auto-tuning here.
-- Produces a numerically checkable output on the host.
-
-Store the file under `<target_path>/artifacts/<slug>/probe.cu`.
-
-### Step 3 — Compile
-
-```bash
-nvcc -arch=sm_90a -O3 -std=c++17 -lineinfo -o probe probe.cu
-```
-
-Record the exact command in `artifacts.build` (either the literal command string or a path to a `build.sh`). On compile failure, record the ptxas/nvcc message verbatim in the probe record and set `status: failed`.
-
-### Step 4 — Run, verify, measure
-
-Follow `benchmark-protocol.md` strictly:
-- 5 warmup launches (discarded).
-- 20 measurement launches via CUDA events; record median + p10 + p90.
-- Reference implementation (torch or hand-written scalar) compared with `max_abs_err` against the tolerance in `benchmark-protocol.md`.
-- Run `kp_introspect kernel-static --binary probe --symbol <kernel>` and attach the JSON as `artifacts.introspection`.
-
-### Step 5 — Write the probe record
-
-Path: `sources/experience/api-probes/<YYYY-MM-DD>-<ns>-<func-slug>.md`. Frontmatter: exactly what `templates/frontmatter/experience.yaml` specifies — no extra fields, no missing fields. Body sections, in order:
-
-1. `## Summary` — one paragraph: what was probed, on what hardware, result in one sentence.
-2. `## Minimal Kernel` — the `.cu` source verbatim (fenced code block).
-3. `## Build` — the exact nvcc command.
-4. `## Measurement` — the benchmark table (per `benchmark-protocol.md` Pillar 4).
-5. `## Introspection` — one-line summary plus path to the bundle json.
-6. `## Notes` — pitfalls, reference hits from Step 1, open questions.
-
-### Step 6 — Back-fill `wiki/nvidia/api-definitions/`
-
-If `wiki/nvidia/api-definitions/<ns>/<func>.md` already exists: append a `## End-to-End Example` section with a link to the probe record, and flip `has_end_to_end_example: true` in the frontmatter.
-
-If it doesn't exist: create it now using `templates/frontmatter/api-raw.yaml`, with the signature extracted from upstream (Step 1) and a link to the probe record under `probed_by:`.
-
-## Failure modes (MVP handling)
-
-| Condition | What to do |
-| --- | --- |
-| Zero upstream hits | `kind: undocumented`, `status: blocked`, stop, ask human. |
-| Compile fails | `status: failed`, keep the probe record with the error message, stop. |
-| Correctness fails (max_abs_err exceeds tolerance) | `status: failed`, record the observed error, stop. |
-| Latency not interesting (single call < 0.01 ms) | Still record; the probe is for *semantics*, not performance. Set `evidence_level: measured` anyway. |
-| Probe passes but contradicts upstream doc | **Out of MVP scope** (discrepancy handling). Record the observation in `## Notes`, `status: verified`, and file an issue. |
-
-## Out of scope (skeleton version)
-
-- Full discrepancy handling and automatic `cuda-official` annotation.
-- Multi-kernel probes (cluster-wide, multi-CTA coordination).
-- NVML-backed `clock_policy` verification (until M5).
-- Cross-run deduplication via a provenance index.

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

@@ -1,109 +0,0 @@
-# Benchmark Protocol (N2, skeleton)
-
-> **Version**: MVP skeleton. Four non-negotiable pillars. NVML-backed clock
-> policy verification is deferred to M5; until then `clock_policy: unknown`
-> is allowed and auto-downgrades `evidence_level` to `inferred`.
-
-The purpose of this protocol is to ensure any two benchmark records in this KB can be compared directly. "Faster" means nothing without warmup, repeat, baseline, and clock policy being identical — or at least explicit.
-
-## Pillar 1 — Correctness before performance
-
-Every benchmark computes a **reference result** and verifies the kernel matches it **before** recording any latency.
-
-- Reference is one of: `torch.<op>`, a hand-written scalar CPU version, or a library call (`cub::Device<Op>`, `cuBLAS*`).
-- Tolerance defaults (override in `verified.md` when needed):
-  - `fp32` → `max_abs_err <= 1e-5`
-  - `fp16` / `bf16` → `max_abs_err <= 1e-3`
-  - `int32` → exact match
-- On mismatch: abort benchmark, record `status: failed`, observed error, and the inputs that triggered it. **No fast-but-wrong records.**
-
-## Pillar 2 — Warmup and repeat
-
-Use CUDA events for timing. Never use wall-clock or CPU timers for per-launch latency.
-
-- **Warmup**: 5 launches, discarded.
-- **Measure**: 20 launches, record median (primary), p10, and p90.
-- **One measurement per launch** — no inside-loop timing.
-- **Synchronize explicitly** between launches when the kernel is async w.r.t. the host.
-
-Canonical harness (C++):
-
-```cpp
-cudaEvent_t e_start, e_end;
-cudaEventCreate(&e_start);
-cudaEventCreate(&e_end);
-
-for (int i = 0; i < 5; ++i) run_kernel();           // warmup
-cudaDeviceSynchronize();
-
-std::vector<float> times_ms;
-for (int i = 0; i < 20; ++i) {
-    cudaEventRecord(e_start);
-    run_kernel();
-    cudaEventRecord(e_end);
-    cudaEventSynchronize(e_end);
-    float ms; cudaEventElapsedTime(&ms, e_start, e_end);
-    times_ms.push_back(ms);
-}
-std::sort(times_ms.begin(), times_ms.end());
-float median = times_ms[10];
-float p10    = times_ms[2];
-float p90    = times_ms[18];
-```
-
-Python/torch equivalent is allowed when the kernel is invoked via torch bindings:
-
-```python
-for _ in range(5): run_kernel(); torch.cuda.synchronize()
-starts = [torch.cuda.Event(enable_timing=True) for _ in range(20)]
-ends   = [torch.cuda.Event(enable_timing=True) for _ in range(20)]
-for i in range(20):
-    starts[i].record()
-    run_kernel()
-    ends[i].record()
-torch.cuda.synchronize()
-times_ms = sorted(starts[i].elapsed_time(ends[i]) for i in range(20))
-```
-
-## Pillar 3 — Clock policy
-
-Record whether the GPU clock was locked or free-running.
-
-- `locked`: `nvidia-smi --lock-gpu-clocks=<freq>` was issued and still effective during the run.
-- `auto`: default free-running clocks.
-- `stable-auto`: free-running but std/mean < 2% across 5 samples 200 ms apart.
-- `unknown`: MVP default when NVML is not available. **Auto-downgrades `evidence_level` to `inferred`.**
-
-MVP rule: set `clock_policy: unknown` unless you explicitly locked clocks. Do not guess `stable-auto` — M5 will add a real detector.
-
-## Pillar 4 — Baseline is mandatory
-
-Every measurement records at least one baseline in the **same benchmark table**.
-
-Allowed baselines (pick whichever matches the layer):
-- `torch.<op>` — default for Python-level tasks.
-- `cub::Device<Op>` / `cub::Block<Op>` — default for CUB-style tasks.
-- `cuBLAS` / `cuBLASLt` / `cuDNN` call — for library-comparable kernels.
-- A named hand-written baseline when no library path exists (e.g. `naive_reduce_v0`).
-
-Never report a speedup without naming the baseline.
-
-## Mandatory output schema
-
-Every probe record under `sources/experience/api-probes/` or `sources/experience/hw-probes/` MUST include a table with exactly these columns (MVP: `verified.md` is dropped; benchmark data never lives in `skill.md` directly, it lives in the probe record and `skill.md` links to it):
-
-| shape | dtype | latency_ms_median | latency_ms_p10 | latency_ms_p90 | baseline_name | baseline_ms | ratio | clock_policy | reproduce_cmd |
-
-Where:
-- `ratio = baseline_ms / latency_ms_median` (>1 means the kernel is faster than baseline).
-- `reproduce_cmd` is a single shell command the reader can copy-paste to re-run.
-- Missing any column → `lint_knowledge.py` rejects the file.
-
-## Anti-patterns (lint will reject)
-
-1. Reporting median only, without p10/p90.
-2. Recording latency without specifying a baseline.
-3. Using `cudaDeviceSynchronize()` as a timer.
-4. Timing a loop body that contains multiple kernel launches.
-5. Writing `clock_policy: locked` without running the lock command.
-6. Comparing against a baseline on different hardware or different dtype.

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

@@ -1,106 +0,0 @@
-# Bottleneck → Next Skill (simplified)
-
-> **Version**: MVP skeleton. No NCU metric auto-selection; no limit_factor
-> driven routing. Those depend on `kp_introspect` being fully wired and are
-> deferred to M5+.
-
-After a benchmark run, this document tells the agent which skill to pull next when the current implementation does not meet the success criteria.
-
-## Inputs
-
-- The latest `verified.md` table (from the skill being built or the probe being run).
-- `kp_introspect bundle` output (`artifacts.introspection`).
-- Optional: `ncu` output for the same shape (not required in MVP).
-
-## Decision tree
-
-```
-Q1. Did correctness fail?
-    YES → Stop. Do not pick a new skill until correctness is restored.
-          Record the failure in pitfalls.md.
-    NO  → Continue.
-
-Q1b. Does wall-clock exceed on-GPU kernel time by a fixed host-side offset?
-    Symptom: nsys per-launch duration > NCU kernel duration by ≈1.7 μs on H200,
-    OR NCU Compute SOL < 10 % on a tiny-grid kernel, OR you are launching
-    many small kernels and per-launch overhead dominates cumulative time.
-    YES → pull 90-system-level/launch-overhead/ first; kernel-internal skills
-          will not move wall-clock until the launch floor is addressed (or the
-          workload is batched / graph-captured).
-    NO  → Continue.
-
-Q2. Is `kernel.dynamic.limit_factor` known from the introspection bundle?
-    register-bound → pull wiki/nvidia/foundations/memory/register-pressure/
-                   + wiki/nvidia/foundations/compute/compiler-hints/
-                   (reduce regs/thread via __launch_bounds__, -maxrregcount,
-                    or by splitting loops)
-    shmem-bound    → pull wiki/nvidia/foundations/memory/bank-conflict/
-                   + check vectorized-access / layout-transform
-                   (reduce shmem per block or the bank-conflict factor)
-    thread-bound   → DEFERRED in MVP — report and ask human.
-    unknown        → Continue to Q3.
-
-Q3. Compare median latency against baseline_ms:
-    ratio >= 0.95 → Chain converged. Finalize verified.md and stop.
-    0.5 <= ratio < 0.95 → Apply Q4 micro-diagnosis.
-    ratio < 0.5 → Fundamental approach wrong. Re-check the pattern INDEX.md
-                  (library-fallback may be the right answer) and stop.
-
-Q4. Micro-diagnosis by inspection (no NCU required):
-    - Reads/writes memory with stride > 1 per thread
-      → pull wiki/nvidia/foundations/memory/coalescing/
-    - Per-element scalar load/store when dtype * 4 fits a vector
-      → pull wiki/nvidia/foundations/memory/vectorized-access/
-    - Thread 0 (or lane 0) does a serial reduction
-      → pull wiki/nvidia/foundations/compute/warp-primitives/
-    - Small tight loop inside kernel without #pragma unroll / ILP
-      → pull wiki/nvidia/foundations/compute/ilp/
-    - Heavy use of sinf/cosf/expf/logf on fp32 with relaxed precision ok
-      → pull wiki/nvidia/foundations/compute/fast-math/
-    - Narrow reduction into smem with heavy bank contention
-      → pull wiki/nvidia/foundations/memory/bank-conflict/
-    - Data race or inconsistent cross-thread reads
-      → pull wiki/nvidia/foundations/sync/memory-ordering/
-
-Q4b. Bytes-in-flight analysis (Little's Law, from GTC25-S72683):
-    If Q4 skills have been applied but BW utilization (from ncu or wall-clock
-    vs theoretical peak) is still < 85%:
-
-    Estimate bytes-in-flight per SM:
-      BiF = loads/thread × bytes/load × threads/block × blocks/SM
-
-    Target: H200 needs ~64 KiB/SM for >90% BW utilization.
-    If BiF < target:
-      - Already using unroll + vectorized loads (register prefetch)?
-        → consider wiki/nvidia/foundations/memory/async-copy/ (LDGSTS + cuda::pipeline)
-        → async copies skip the register file, freeing regs for compute
-        → BUT: only helps compute-heavy or iterative kernels (GTC25-S72683
-          showed trivial a*b got NO benefit; sqrt-heavy got 1.3× uplift)
-      - Still not enough? Check stage count:
-        stages_needed = ceil(target_BiF / (2 × bytes/load × threads/block × blocks/SM))
-        → H200 with 256 threads/block at 100% occ: 2 stages minimum
-
-    See optimization flow chart:
-    ![Optimization guidelines](<local-path>
-
-Q5. After pulling a skill and modifying the kernel, rerun the benchmark
-    and go back to Q1.
-```
-
-## Loop cap
-
-**Max 3 iterations** per task. After three rounds, if the success criteria still are not met, record `status: stuck_at_<ratio>` in the output and surface the case in the done-report for human review. Do not spin forever.
-
-## What goes into `pitfalls.md` each iteration
-
-Each iteration that did not fully converge contributes one entry to `pitfalls.md` of the skill being built, with:
-- observed symptom (e.g. `ratio 0.72 vs torch.sum, dtype=fp32, shape=4096`)
-- hypothesis (e.g. `non-coalesced loads`)
-- skill pulled (e.g. `coalescing`)
-- outcome (e.g. `ratio 0.94 after vectorized `float4` loads`)
-
-## Out of scope (skeleton version)
-
-- NCU metric auto-selection by bottleneck hypothesis (full I3/I4 of booklet 05).
-- Automatic skill suggestion via the `limit_factor` decision tree in booklet 07 §R.8.6.
-- Multi-skill composition (some tasks need to apply 2 skills simultaneously — MVP picks one at a time).