From d95a86f0c514f21d7ed6eecdeb8226e05d473544 Mon Sep 17 00:00:00 2001 From: Noah Gift Date: Fri, 16 Oct 2026 16:49:58 +0200 Subject: [PATCH 1/5] =?UTF-8?q?docs(claude-md):=20context=20trim=20?= =?UTF-8?q?=E2=80=94=20code-search=20block=20pointed=20at=20the=20global?= =?UTF-8?q?=20policy,=20stale=20SSC=20snapshot=20moved=20to=20docs/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md 38.6 -> 36.0 KB. Headings kept (contracts/ontology.yaml classifies them). Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 80 ++++---------------------- docs/ssc-training-status-2026-03-22.md | 14 +++++ 2 files changed, 25 insertions(+), 69 deletions(-) create mode 100644 docs/ssc-training-status-2026-03-22.md diff --git a/CLAUDE.md b/CLAUDE.md index efd71797c5..cf8d82861d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -584,66 +584,16 @@ verify-bindings, migrate`. ## CRITICAL: Code Search Policy -**NEVER use grep/glob for code search. ALWAYS use pmat query.** +**NEVER use grep/glob for code search. ALWAYS use `pmat query`.** The full decision tree, enrichment flags +(`-G`, `--churn`, `--duplicates`, `--entropy`, `--faults`), search modes (`--regex`, `--literal`) and coverage-gap +workflow are in the global `~/.claude/CLAUDE.md` Code Search Policy; this repo adds only the cross-project index +note and the coverage + contracts rule below. -### Decision Tree - -| Task | Command | -|------|---------| -| Find functions by intent | `pmat query "error handling" --limit 10` | -| Find important functions | `pmat query "mcp" --rank-by pagerank --limit 5` | -| Find most-called utilities | `pmat query "format" --rank-by indegree --limit 5` | -| Find in specific path | `pmat query "validate" --path src/api/` | -| Find high-quality code only | `pmat query "parse" --min-grade B --max-complexity 15` | - -### Examples - -```text -# BAD - Raw text search returns 500+ noisy matches with no context -# GOOD - Semantic search returns 10 ranked functions with quality metrics -pmat query "error handling" --limit 10 -``` - -### Cross-Project Search - -The index automatically includes sibling projects (aprender, trueno, realizar). -Query from any project to search 60k+ functions across all three codebases. - -```text -# Build index in each project first (one-time setup) -cd ~/src/aprender && pmat query "init" --rebuild-index --limit 1 -cd ~/src/trueno && pmat query "init" --rebuild-index --limit 1 -cd ~/src/realizar && pmat query "init" --rebuild-index --limit 1 - -# Now query from any project - siblings auto-merge -pmat query "matrix multiplication" --limit 5 -``` - -### Output Formats - -- Default (text): Human-readable with signatures and metrics -- `--format json`: For parsing/scripting -- `--format markdown`: For documentation -- `--include-source`: Include full source code in results - -### Quick Reference - -```text -pmat query "" # Basic search -pmat query "" --rank-by pagerank # Most important functions -pmat query "" --format json # Machine-readable -pmat query "" --include-source # Include full source code -pmat query "" --exclude-tests # Skip test functions - -# Git history search (find code by commit intent via RRF fusion) -pmat query "fix serialization" -G -pmat query "apr format" --git-history - -# Enrichment flags (combine freely) -pmat query "ml algorithm" --churn # git volatility (commit count, churn score) -pmat query "tensor operation" --duplicates # code clone detection (MinHash+LSH) -pmat query "loss function" --entropy # pattern diversity (repetitive vs unique) -pmat query "model training" --churn --duplicates --entropy --faults -G # full audit +```bash +pmat query "" --limit 10 --include-source # semantic search with quality annotations +pmat query "" --rank-by pagerank # most important functions +# Siblings (aprender, trueno, realizar) auto-merge into the index; build once per project: +pmat query "init" --rebuild-index --limit 1 ``` ### Coverage-Guided Search (pmat 3.0.0+) @@ -687,15 +637,7 @@ batuta oracle --rag-index # Reindex (the command prints the do Use proactively for trueno SIMD patterns, cross-language equivalents, and stack best practices. -## SSC Training Infrastructure Status (snapshot 2026-03-22 — STALE, re-verify before acting) -This block has not been re-measured in ~5 months and one of its premises no longer -holds: it points at "trueno 0.4.36" as an external crate, but since APR-MONO trueno is -in-tree as `crates/aprender-compute` and has no independent version to wait on. +## SSC Training Infrastructure Status -- **SSC canary eval**: 90% accuracy, SHIP gate PASS — classifier ready to ship -- **entrenar cuBLAS integration**: GEMM parity verified between CPU and GPU paths -- **Blackwell (GB10) training**: Blocked by JIT pre-warming bug in custom PTX kernels. Must use fused NF4 kernel path until trueno 0.4.36 ships with pre-compiled kernels -- **apr-cli inference NOT affected**: `apr run` / `apr serve` use cuBLAS (GPU) or trueno SIMD (CPU) — pre-compiled, no custom PTX involved -- **Trained model (LoRA adapter)**: Architecture-independent safetensors — works on any GPU or CPU via standard PEFT loading -- **Key tickets**: trueno#200 (Blackwell JIT), trueno#203 (pre-compiled kernels), entrenar#300 (cuBLAS backward) +Moved to `docs/ssc-training-status-2026-03-22.md` (a 2026-03-22 snapshot, stale; re-verify before acting). diff --git a/docs/ssc-training-status-2026-03-22.md b/docs/ssc-training-status-2026-03-22.md new file mode 100644 index 0000000000..ec297a9e25 --- /dev/null +++ b/docs/ssc-training-status-2026-03-22.md @@ -0,0 +1,14 @@ +# SSC training infrastructure status (snapshot 2026-03-22, STALE) + +Moved out of CLAUDE.md in the 2026-10-16 context trim. Re-verify before acting. + +This block has not been re-measured in ~5 months and one of its premises no longer +holds: it points at "trueno 0.4.36" as an external crate, but since APR-MONO trueno is +in-tree as `crates/aprender-compute` and has no independent version to wait on. + +- **SSC canary eval**: 90% accuracy, SHIP gate PASS — classifier ready to ship +- **entrenar cuBLAS integration**: GEMM parity verified between CPU and GPU paths +- **Blackwell (GB10) training**: Blocked by JIT pre-warming bug in custom PTX kernels. Must use fused NF4 kernel path until trueno 0.4.36 ships with pre-compiled kernels +- **apr-cli inference NOT affected**: `apr run` / `apr serve` use cuBLAS (GPU) or trueno SIMD (CPU) — pre-compiled, no custom PTX involved +- **Trained model (LoRA adapter)**: Architecture-independent safetensors — works on any GPU or CPU via standard PEFT loading +- **Key tickets**: trueno#200 (Blackwell JIT), trueno#203 (pre-compiled kernels), entrenar#300 (cuBLAS backward) From 319bf6a92fdf0e56afc656e1cf16b208fe341505 Mon Sep 17 00:00:00 2001 From: Noah Gift Date: Fri, 16 Oct 2026 16:50:54 +0200 Subject: [PATCH 2/5] docs(claude-md): keep a self-contained code-search flag list (review: global file is author-local) Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cf8d82861d..32a492d5b7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -586,13 +586,17 @@ verify-bindings, migrate`. **NEVER use grep/glob for code search. ALWAYS use `pmat query`.** The full decision tree, enrichment flags (`-G`, `--churn`, `--duplicates`, `--entropy`, `--faults`), search modes (`--regex`, `--literal`) and coverage-gap -workflow are in the global `~/.claude/CLAUDE.md` Code Search Policy; this repo adds only the cross-project index -note and the coverage + contracts rule below. +workflow are in the author-local `~/.claude/CLAUDE.md`; the commands every contributor needs are kept here, plus the coverage + contracts rule below. ```bash pmat query "" --limit 10 --include-source # semantic search with quality annotations pmat query "" --rank-by pagerank # most important functions -# Siblings (aprender, trueno, realizar) auto-merge into the index; build once per project: +pmat query "" --rank-by indegree # most-called utilities +pmat query "" --path src/api/ # restrict to a path +pmat query "" --format json # or markdown; default is text +pmat query "" --min-grade B --max-complexity 15 --exclude-tests +pmat query "" -G # fuse git-history intent (also --churn --duplicates --entropy --faults) +# Siblings (aprender, trueno, realizar; 60k+ functions) auto-merge into the index; build once per project: pmat query "init" --rebuild-index --limit 1 ``` From 5f7e2b0a6ceca39a7f0d404ff440fef8505fc453 Mon Sep 17 00:00:00 2001 From: Noah Gift Date: Fri, 16 Oct 2026 16:51:35 +0200 Subject: [PATCH 3/5] docs(claude-md): keep the SSC heading text byte-identical (contracts.nt embeds it) Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 32a492d5b7..d973eb6bb4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -642,6 +642,6 @@ batuta oracle --rag-index # Reindex (the command prints the do Use proactively for trueno SIMD patterns, cross-language equivalents, and stack best practices. -## SSC Training Infrastructure Status +## SSC Training Infrastructure Status (snapshot 2026-03-22 — STALE, re-verify before acting) Moved to `docs/ssc-training-status-2026-03-22.md` (a 2026-03-22 snapshot, stale; re-verify before acting). From 71a70d1cc33ee2097b67c5187b7f61bf43e497d1 Mon Sep 17 00:00:00 2001 From: Noah Gift Date: Fri, 16 Oct 2026 16:55:23 +0200 Subject: [PATCH 4/5] chore(contracts): regenerate contracts.nt for the CLAUDE.md trim (referencedPath: SSC doc replaces a dropped glob mention) Co-Authored-By: Claude Sonnet 5.5 --- contracts/contracts.nt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contracts/contracts.nt b/contracts/contracts.nt index c34b6bfbee..86f7b06242 100644 --- a/contracts/contracts.nt +++ b/contracts/contracts.nt @@ -23382,7 +23382,6 @@ "crates/"^^ . "crates/apr-cli/"^^ . "crates/apr-cli/Cargo.toml"^^ . - "crates/aprender-compute"^^ . "crates/aprender-compute/"^^ . "crates/aprender-contracts-cli/"^^ . "crates/aprender-contracts-macros/"^^ . @@ -23407,6 +23406,7 @@ "crates/aprender-train/"^^ . "docs/BEATS.md"^^ . "docs/specifications/aprender-monorepo-consolidation.md"^^ . + "docs/ssc-training-status-2026-03-22.md"^^ . "scripts/apr_bin.sh"^^ . "scripts/bump-version.sh"^^ . "scripts/check_clippy_current_stable.sh"^^ . From 107e12015bf70c80f461b83fd4a0e05dbadf691a Mon Sep 17 00:00:00 2001 From: Noah Gift Date: Sun, 18 Oct 2026 10:42:49 +0200 Subject: [PATCH 5/5] docs(claude-md): pmat query examples in a text fence, not bash (ONT-4c claim fence; extractor refused the placeholders) Co-Authored-By: Claude Sonnet 5.5 --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index d973eb6bb4..06bc6d5912 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -588,7 +588,7 @@ verify-bindings, migrate`. (`-G`, `--churn`, `--duplicates`, `--entropy`, `--faults`), search modes (`--regex`, `--literal`) and coverage-gap workflow are in the author-local `~/.claude/CLAUDE.md`; the commands every contributor needs are kept here, plus the coverage + contracts rule below. -```bash +```text pmat query "" --limit 10 --include-source # semantic search with quality annotations pmat query "" --rank-by pagerank # most important functions pmat query "" --rank-by indegree # most-called utilities